Informizely customer feedback surveys
By using the Aculab site, you agree with our use of cookies.

UAS API - Outbound Send Fax Sample Application

  • Filename:

    samples/outbound_send_fax.py

    Description:

    A sample application that will place a call and send a fax. The sample first creates a FaxToSend object which is the wrapper for the fax document. This object is used to read in two TIFF files to create the fax document to be sent. The first TIFF file is a header and the second is the body. Both TIFF files must already have been uploaded to the cloud. It is assumed that the name of the header file will be read from the application_parameters variable, which is configured on the Outbound Services page (Manage -> Outbound Services), and the name of the body is read from outbound_parameters.

    After creating the fax document object (my_fax = FaxToSend()), the header file is read in using the my_fax.set_content() function. Then the body is appended to by calling the my_fax.append() function. The application then demonstrates adding a page number to each page by configuring a page text object and then calling the my_fax.add_text_to_page() function on each page.

    The application now places the outbound call. The call destination and the call origin are supplied in outbound_parameters and application_parameters respectively (along with body and header in a semi-colon delimited string).

    The fax transmission is started by calling the channel.FaxSender.start() function and supplying a reference to the fax document object. The application then waits for the fax settings to be negotiated, channel.FaxSender.wait_for_negotiated_settings(), and prints them to the screen. It then uses channel.FaxSender.wait_for_next_page() to wait for each page to be sent, it does this until the last page has been indicated, and prints out the number of pages sent so far.

    Finally, the function channel.FaxSender.wait_until_finished() is used to wait until the fax session has completed. After that, the call is hung up.

    Code:

    """
    A simple example that will place a call and send a fax.
    
        Actions:
            - place a call
            - send a fax
            - hang up
    
    This sample uses two documents, a 'header' page and the
    fax 'body'. It is assumed that application_parameters is
    the name of the header page, and outbound_parameters is the
    name of the body.
    
    Several other assumptions are noted in the code comments.
    
    This application requires that call_from is supplied in 
    application_parameters (this is configured on the outbound 
    service page of the CWP). 
    
    For information on placing outbound calls please read the online 
    web services documentation.
    
    For additional information regarding outbound PSTN calls, please see the 
    online documentation.
    
    Also have a look at the invoke_outbound_service sample code in the 
    samples_ws directory.
    
    """
    
    from prosody.uas import Hangup, Error, FaxToSend, FaxToReceive
    
    __uas_identify__ = "application"
    __uas_version__  = "0.01b"
    
    def main(channel, application_instance_id, file_man, my_log, application_parameters, outbound_parameters):
        try:
            return_code = 0
    
            # in this sample the call origin and fax header name are given in application_parameters
            origin, fax_header = application_parameters.split(';')
            
            # get the call destination and the fax body name from outbound_parameters
            destination, fax_body = outbound_parameters.split(';')
            
            # This outbound application is going to send a fax, so we create
            # a FaxToSend object, known as a fax document object
            my_fax = FaxToSend()
    
            # Now set the content of the fax document object, this is read from
            # a TIFF media file which must be present on the cloud. In this case
            # the content is a fax header, to which more content will be added.
            cause = my_fax.set_content(fax_header)
    
            # The cause will be of type FileCause and should be checked.
            if cause != my_fax.FileCause.NORMAL:
                raise Error("failed to set fax content, cause is {0}".format(cause))
    
            # Add the main fax body to the document.
            cause = my_fax.append(fax_body)
            if cause != my_fax.FileCause.NORMAL:
                raise Error("failed to set fax content, cause is {0}".format(cause))
    
            # Add the page number to each page of the fax document.
            # First create a PageText object.
            page_text = my_fax.create_page_text()
    
            # We want the page number to be one inch from the top of the page.
            # So we set the unit of measurement to inches.
            page_text.Position.unit = page_text.Position.PagePositionUnits.INCHES
            page_text.Position.from_page_top = 1
    
            # We want the existing line at our pgae number position to be completely removed
            page_text.mode = page_text.PageTextMode.REPLACE
    
            # On each page put the page number on the left
            for i in range(my_fax.pages_to_send):
                page_text.left_text = 'This is page {0}'.format(i + 1)
                # page numbers start a 1
                cause = my_fax.add_text_to_page(i + 1, page_text)
                if cause != my_fax.FileCause.NORMAL:
                    raise Error("failed to set fax content, cause is {0}".format(cause))
    
            # Place the outbound call in the normal way
            if channel.call(destination, call_from=origin) != channel.State.ANSWERED:
                cause = channel.cause()
                raise Error("Call destination returned cause {0}".format(cause))
    
            # Now we can start sending the fax.
            if channel.FaxSender.start(fax_to_send=my_fax) is not True:
                cause = channel.FaxSender.cause()
                raise Error("fax sender failed to start sending the fax, cause is {0}.".format(cause))
    
            # The fax endpoints will negotiate the parameters for the fax session - which modem
            # and the modem speed, among other things. We can wait until these have been published
            # and then have a look. Note that the dictionary will be empty if fax negotiation fails.
            negotiated_settings = channel.FaxSender.wait_for_negotiated_settings()
            if negotiated_settings == {}:
                cause = channel.FaxSender.cause()
                if cause == channel.FaxSender.Cause.NOTFAX:
                    raise Hangup("The receiver was not a fax machine.")
                else:
                    raise Error("Fax negotiation failed with cause {0}".format(cause))
    
            my_log.debug("Negotiated Settings")
            for setting, value in negotiated_settings.items():
                my_log.debug("{0:>15.15} : {1}".format(setting, value))
    
            # Now we can wait for each page to be sent, we do this until we've been told
            # that no more pages will be sent. It is important to note that the last_page
            # flag does not indicate success, it simply means that no more pages will be processed.
            while channel.FaxSender.Details.last_page is not True:
                pages = channel.FaxSender.wait_for_next_page()
                my_log.debug("Sent {0} pages so far".format(pages))
    
            # Now we need to wait until the fax session has finished. We need to do this even though
            # the last page flag has been set. Remember to check the cause, the last_page indicator
            # may have been set, but this does not mean that every page was sent.
            cause = channel.FaxSender.wait_until_finished()
            if cause != channel.FaxSender.Cause.NORMAL:
                raise Error("The fax sender failed with cause {0}".format(cause))
    
            # In faxing, it is the receiver that hangs up first, so it is polite
            # for the fax sender to wait for the other end to hang up.
            channel.wait_for_idle()
    
        except Hangup as exc:
            my_log.info("Hangup exception reports {0}".format(exc))
            return_code = -101
    
        except Error as exc:
            my_log.error("Error exception reports {0}".format(exc))
            return_code = -100
    
        except Exception as exc:
            my_log.exception("Got unexpected exception {0}".format(exc))
            return_code = -102
    
        finally:
            if channel.state() != channel.State.IDLE:
                channel.hang_up()
        return return_code
    
  • Filename:

    Samples\UASApplications\OutboundSendFax\src\main\java\com\aculab\uas\app\OutboundSendFax.java

    Description:

    For this sample application, the 'Enable fax send' option needs to be ticked in the fax tab of your Outbound Service that will invoke it. Typically the default fax options provided will result in a fax being sent successfully. The Outbound Service may also specify in the applicationParameters the name of a .tif file that exists on the cloud, the first page of which is to be used as a header page for the sent fax.

    The content of the fax document to send is specified via the outboundParameters argument that originates from the entity that invoked the Outbound Service. This needs to be set to the name of a .tif file that exists on the cloud that contains 1 or more pages.

    The UASApplication object exposes the single fax document that can be sent on an outgoing call. The sample first sets the content of this document to be the 1st page of the file specified in the applicationParameters argument. It then appends all the pages from the content file specified in the outboundParameters argument. Finally, it adds some page number text to each page in the fax document.

    The sample then makes an outbound call using the destination and source addresses specified in applicationParameters and calls the channel.getFaxSender().send() method to send the fax. If successful this will return FaxCause.Normal. Note: this sample relies on the UAS framework to hang up the outbound call.

    Code:

    package com.aculab.uas.app;
    
    // An outbound application that makes a call to a destination address (passed in)
    // from a source address (passed in) and sends a fax to that call.
    //
    // The fax is constructed from a single header page and 1 or more content pages.
    // The header page is obtained from a .tif file specified in the service's application parameters.
    // The content pages are obtained from a .tif file specified in the outboundParameters.
    //
    // A page number is inserted into each page before sending.
    //
    // Fax sending can be enabled for a particular service by editing the service entry
    // from the Outbound Services (or Inbound Services). 
    //
    // If the destination address is a PSTN number then check the Outbound Calls documentation 
    // for your platform for details on requirements for source address.
    //
    // Requires:
    // [outboundParameters = destination address ; source address ; file name of fax]
    // [Fax Send to be enabled in the service invoking this application]
    //
    // Optional:
    // [applicationParameters = file name (.tif) of header page]
    //
    // e.g. 
    // outboundParameters = "sip:bob@bobscompany.com;;ContractFax.tif"
    // or
    // outboundParameters = "441908081876;441908876543;ContractFax.tif"
    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 OutboundSendFax extends UASOutboundApplication
    {
        // Success Codes:
        final int Success = 0;
        // ... any positive integer
    
        // Fail Codes:
        // -1 to -99 reserved
        final int ArgumentError = -101;
        final int FaxSendFailed = -102;
    
        // This is the entry point for the application
        @Override
        public int run(UASCallChannel channel,
                       String applicationParameters, // fax header page file name (.tif) - optional
                       String outboundParameters)    // destination address ; source address ; fax content file name (.tif)
            throws Exception
        {
            this.getTrace().traceInfo("Start - appParms [%s] outParms [%s]",
                    applicationParameters,
                    outboundParameters);
            int returnCode = Success;
    
            // Check we have been given a destination address, source address and fax content file name
            String[] splits = outboundParameters.split(";");
            if (splits.length < 3)
            {
                this.getTrace().traceError("This app requires a destination address, source address and fax file name, in the outboundParameters field");
                return ArgumentError;
            }
            String destinationAddress = splits[0];
            String sourceAddress = splits[1];
            String faxFileName = splits[2];
    
            // The fax header file may be empty
            String faxHeaderFileName = applicationParameters;
    
            // Format the fax to send
            FaxToSend faxToSend = this.getFaxToSend();
    
            if ((faxHeaderFileName != null) && 
                (!faxHeaderFileName.isEmpty()))
            {
                // Set the first page to that in the header file
                faxToSend.setContent(faxHeaderFileName, 1, 1);
            }
    
            // Append all pages from the contents file to the fax
            faxToSend.append(faxFileName);
    
            // Add page numbers to all pages, centred
            FaxPageText text = new FaxPageText(null, null, null);
            for (int page = 1; page <= faxToSend.getDetails().getPagesToSend(); page++)
            {
                text.setCentreText(String.format("[page %d]", page));
                faxToSend.addTextToPage(page, text, FaxPageTextMode.Insert);
            }
    
            // Set fax options:
            // Just set this end's subscriber id.
            // (this overrides any set in the service registration)
            FaxOptions options = new FaxOptions("SubscriberId", "5678");
    
            // Make a call
            CallState state = channel.call(destinationAddress, sourceAddress);
            if (state == CallState.Answered)
            {
                this.getTrace().traceInfo("Call answered");
    
                // Now send the fax
                this.getTrace().traceInfo("Sending fax %s", faxFileName);
                FaxCause cause = channel.getFaxSender().send(faxToSend, options);
                if (cause != FaxCause.Normal)
                {
                    this.getTrace().traceError("Failed to send fax: cause %s", channel.getFaxSender().getCause().toString());
                    returnCode = FaxSendFailed;
                }
                else
                {
                    // Received ok, now retrieve some of the negotiated fax options
                    // used to send/receive the fax.
                    FaxOptions negotiatedOptions = this.getFaxToSend().getDetails().getNegotiatedOptions();
                    String receivingSubscriberId = negotiatedOptions.getItem("remotesubscriberid");
                    this.getTrace().traceInfo("Sent fax to subscriber Id: %s", receivingSubscriberId);
                }
            }
    
            this.getTrace().traceInfo("Completed");
            return returnCode;
        }
    }
    
  • Filename:

    Samples\C#\OutboundSendFax\OutboundSendFax.cs

    Description:

    For this sample application, the 'Enable fax send' option needs to be ticked in the fax tab of your Outbound Service that will invoke it. Typically the default fax options provided will result in a fax being sent successfully. The Outbound Service may also specify in the applicationParameters the name of a .tif file that exists on the cloud, the first page of which is to be used as a header page for the sent fax.

    The content of the fax document to send is specified via the outboundParameters argument that originates from the entity that invoked the Outbound Service. This needs to be set to the name of a .tif file that exists on the cloud that contains 1 or more pages.

    The UASApplication object exposes the single fax document that can be sent on an outgoing call. The sample first sets the content of this document to be the 1st page of the file specified in the applicationParameters argument. It then appends all the pages from the content file specified in the outboundParameters argument. Finally, it adds some page number text to each page in the fax document.

    The sample then makes an outbound call using the destination and source addresses specified in applicationParameters and calls the channel.FaxSender.Send() method to send the fax. If successful this will return FaxCause.Normal. Note: this sample relies on the UAS framework to hang up the outbound call.

    Code:

    ´╗┐using System;
    using System.Threading;
    using AMSClassLibrary;
    using UASAppAPI;
    
    // An outbound application that makes a call to a destination address (passed in)
    // from a source address (passed in) and sends a fax to that call.
    //
    // The fax is constructed from a single header page and 1 or more content pages.
    // The header page is obtained from a .tif file specified in the service's application parameters.
    // The content pages are obtained from a .tif file specified in the outboundParameters.
    //
    // A page number is inserted into each page before sending.
    //
    // Fax sending can be enabled for a particular service by editing the service entry
    // from the Outbound Services (or Inbound Services) page for your platform. 
    //
    // If the destination address is a PSTN number then check the Outbound Calls documentation 
    // for your platform for details on requirements for source address.
    //
    // Requires:
    // [outboundParameters = destination address ; source address ; file name of fax]
    // [Fax Send to be enabled in the service invoking this application]
    // 
    // Optional:
    // [applicationParameters = file name (.tif) of header page]
    //
    // e.g. 
    // outboundParameters = "sip:bob@bobscompany.com;;ContractFax.tif"
    // or
    // outboundParameters = "441908081876;441908876543;ContractFax.tif"
    namespace OutboundSendFax
    {
        // 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 OutboundSendFax : UASOutboundApplication
        {
            // Possible return codes
            enum ReturnCode
            {
                // Success Codes:
                Success = 0,
    
                // Fail Codes:
                // -1 to -99 reserved
                ArgumentError = -100,
                FaxSendNotEnabled = -101,
                FaxSendFailed = -102
            }
    
            // This is the entry point for the application
            public override int Run(UASCallChannel channel,
                                    string applicationParameters, // fax header page file name (.tif) - optional
                                    string outboundParameters)    // destination address ; source address ; fax content file name (.tif)
            {
                this.Trace.TraceInfo("Start - appParms [{0}] outParms [{1}]",
                                   applicationParameters,
                                   outboundParameters);
                ReturnCode reply = ReturnCode.Success;
    
                // Check that fax sending has been enabled in the calling service.
                if (this.FaxDocumentToSend == null)
                {
                    this.Trace.TraceError("This app requires that fax sending is enabled in the calling service");
                    return (int)ReturnCode.FaxSendNotEnabled;
                }
    
                // Check we have been given a destination address, source address and fax content file name
                string[] splits = outboundParameters.Split(';');
                if (splits.Length < 3)
                {
                    this.Trace.TraceError("This app requires a destination address, source address and fax file name, in the outboundParameters field");
                    return (int)ReturnCode.ArgumentError;
                }
                string destinationAddress = splits[0];
                string sourceAddress = splits[1];
                string faxFileName = splits[2];
    
                // The fax header file may be empty
                string faxHeaderFileName = applicationParameters;
    
                // Format the fax to send
                if (!String.IsNullOrEmpty(faxHeaderFileName))
                {
                    // Set the first page to that in the header file
                    this.FaxDocumentToSend.SetContent(faxHeaderFileName, 1, 1);
                }
                // Append all pages from the contents file to the fax
                this.FaxDocumentToSend.Append(faxFileName);
    
                // Add page numbers to all pages, centred
                FaxPageText text = new FaxPageText(null, null, null);
                for (int page = 1; page <= this.FaxDocumentToSend.Details.PagesToSend; page++)
                {
                    text.CentreText = String.Format("[page {0}]", page);
                    this.FaxDocumentToSend.AddTextToPage(page, text, FaxPageTextMode.Insert);
                }
    
                // Set fax options:
                // Just set this end's subscriber id.
                // (this overrides any set in the service registration)
                FaxOptions options = new FaxOptions("SubscriberId", "5678");
    
                // Make a call
                CallState state = channel.Call(destinationAddress, sourceAddress);
                if (state == CallState.Answered)
                {
                    this.Trace.TraceInfo("Call answered");
    
                    // Now send the fax
                    this.Trace.TraceInfo("Sending fax {0}", faxFileName);
                    FaxCause cause = channel.FaxSender.Send(this.FaxDocumentToSend, options);
                    if (cause != FaxCause.Normal)
                    {
                        this.Trace.TraceError("Failed to send fax: cause {0}", channel.FaxSender.Cause.ToString());
                        reply = ReturnCode.FaxSendFailed;
                    }
                    else
                    {
                        // Sent ok, now retrieve some of the negotiated fax options
                        // used to send/receive the fax.
                        FaxOptions negotiatedOptions = this.FaxDocumentToSend.Details.NegotiatedOptions;
                        String receivingSubscriberId = negotiatedOptions["remotesubscriberid"];
                        this.Trace.TraceInfo("Sent fax to subscriber Id: {0}", receivingSubscriberId);
                    }
                }
    
                this.Trace.TraceInfo("Completed");
                return (int)reply;
            }
        }
    }
  • Filename:

    Samples\VB\OutboundSendFax\OutboundSendFax.vb

    Description:

    For this sample application, the 'Enable fax send' option needs to be ticked in the fax tab of your Outbound Service that will invoke it. Typically the default fax options provided will result in a fax being sent successfully. The Outbound Service may also specify in the applicationParameters the name of a .tif file that exists on the cloud, the first page of which is to be used as a header page for the sent fax.

    The content of the fax document to send is specified via the outboundParameters argument that originates from the entity that invoked the Outbound Service. This needs to be set to the name of a .tif file that exists on the cloud that contains 1 or more pages.

    The UASApplication object exposes the single fax document that can be sent on an outgoing call. The sample first sets the content of this document to be the 1st page of the file specified in the applicationParameters argument. It then appends all the pages from the content file specified in the outboundParameters argument. Finally, it adds some page number text to each page in the fax document.

    The sample then makes an outbound call using the destination and source addresses specified in applicationParameters and calls the channel.FaxSender.Send() method to send the fax. If successful this will return FaxCause.Normal. Note: this sample relies on the UAS framework to hang up the outbound call.

    Code:

    ´╗┐Imports System
    Imports System.Threading
    Imports System.Text
    Imports AMSClassLibrary
    Imports UASAppAPI
    
    ' An outbound application that makes a call to a destination address (passed in)
    ' from a source address (passed in) and sends a fax to that call.
    '
    ' The fax is constructed from a single header page and 1 or more content pages.
    ' The header page is obtained from a .tif file specified in the service's application parameters.
    ' The content pages are obtained from a .tif file specified in the outboundParameters.
    '
    ' A page number is inserted into each page before sending.
    '
    ' If the destination address is a PSTN number then check the Outbound Calls documentation 
    ' for your platform for details on requirements for source address.
    '
    ' Requires:
    ' [outboundParameters = destination address ; source address ; file name of fax]
    ' [Fax Send to be enabled in the service invoking this application]
    ' 
    ' Optional:
    ' [applicationParameters = file name (.tif) of header page]
    '
    ' e.g. 
    ' outboundParameters = "sip:bob@bobscompany.com;;ContractFax.tif"
    ' or
    ' outboundParameters = "441908081876;441908876543;ContractFax.tif"
    Namespace OutboundSendFax
    
        ' 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 OutboundSendFax
            Inherits UASOutboundApplication
    
            ' Possible return codes
            Enum ReturnCode
                ' Success Codes:
                Success = 0
                ' ... any positive integer
    
                ' Fail Codes:
                ' -1 to -99 reserved
                ArgumentError = -101
                FaxSendFailed = -102
                FaxSendTimedOut = -103
            End Enum
    
            ' This is the entry point for the application
            Overrides Function Run(ByVal channel As UASCallChannel, _
                                   ByVal applicationParameters As String, _
                                   ByVal outboundParameters As String) _
                                   As Integer
    
                Me.Trace.TraceInfo("Start - appParms [{0}] outParms [{1}]", _
                                   applicationParameters, _
                                   outboundParameters)
                Dim reply As ReturnCode = ReturnCode.Success
    
                ' Check we have been given a destination address, source address and fax content file name
                Dim splits As String() = outboundParameters.Split(";")
                If splits.Length < 3 Then
                    Me.Trace.TraceError("This app requires a destination address, source address and fax file name, in the outboundParameters field")
                    Return ReturnCode.ArgumentError
                End If
                Dim destinationAddress = splits(0)
                Dim sourceAddress = splits(1)
                Dim faxFileName = splits(2)
    
                ' The fax header file may be empty
                Dim faxHeaderFileName = applicationParameters
    
                ' Format the fax to send
                If Not String.IsNullOrEmpty(faxHeaderFileName) Then
                    ' Set the first page to that in the header file
                    Me.FaxDocumentToSend.SetContent(faxHeaderFileName, 1, 1)
                End If
                ' Append all pages from the contents file to the fax
                Me.FaxDocumentToSend.Append(faxFileName)
    
                ' Add page numbers to all pages, centred
                Dim text As FaxPageText = New FaxPageText(Nothing, Nothing, Nothing)
                For page = 1 To Me.FaxDocumentToSend.Details.PagesToSend
                    text.CentreText = String.Format("[page {0}]", page)
                    Me.FaxDocumentToSend.AddTextToPage(page, text, FaxPageTextMode.Insert)
                Next page
    
                ' Make a call
                Dim state As CallState = channel.Call(destinationAddress, sourceAddress)
                If state = CallState.Answered Then
                    Me.Trace.TraceInfo("Call answered")
    
                    ' Now send the fax
                    Me.Trace.TraceInfo("Sending fax {0}", faxFileName)
                    Dim cause As FaxCause = channel.FaxSender.Send(Me.FaxDocumentToSend)
                    If Not cause = FaxCause.Normal Then
                        Me.Trace.TraceInfo("Failed to send fax: cause {0}", channel.FaxSender.Cause.ToString())
                        reply = ReturnCode.FaxSendFailed
                    End If
                End If
                
                Me.Trace.TraceInfo("Completed")
                Return reply
    
            End Function
    
        End Class
    
    End Namespace