SDK: detect fax call

The bearer capability information received on an incoming call does not always reliably tell us whether an incoming call is a voice or fax, but sometimes it is important for an app to be able to decide whether a call is a fax so that it can be correctly processed. 

 One way to do this is to listen to the call after physical connection to see whether there is a fax calling tone (also known as CNG) on the line.  All calling fax machines emit this CNG tone periodically, and you can read more about this tone here. 

We can detect this tone in an SDK app, and use this as a signal to switch from voice to fax mode.  

 CNG tone is reported in two ways in the SDK:

 Firstly if we have extended tone detection on (DivaReportTones), then CNG is reported as DivaFaxCallingTone. 

 Secondly, if we have DTMF tone detection on (DivaReportDTMF) then CNG is translated to a special DTMF 'X' (as opposed to the more normal '0'..'9' and '*','#'). 

 So we can quite conveniently see CNG tone in the application and take action.
 

 Here is a suggested algorithm:

1. When an incoming call arrives, answer it as a speech call.  Enable DTMF reporting.  You could also enable echo cancellation (ECR) at this time. 

2. Play a suitable greeting message in case the caller is a human.  If ECR is on, this will help the tone detection to be more reliable, since any echo from the outgoing message can be subtracted from the received audio stream.

3. Now process any incoming DTMF digits.  If a DTMF 'X' arrives, use DivaSetCallTypeFax to switch from speech to fax mode.  CNG is sent every 3 seconds, so if you haven't seen 'X' after 7 seconds, then you probably won't.

4. When the connect event comes in (which indicates that the T.30 fax handshake is all done and the fax session is established) use DivaReceiveFax to save the incoming fax to a file (TIFF,G3,SFF).

5. Now the fax processing procedes as normal, with the SDK sending DivaEventFaxPageReceived and DivaEventFaxReceivedprogress messages to the app.