freetdm: update glare.txt doc

diff --git a/libs/freetdm/docs/glare.txt b/libs/freetdm/docs/glare.txt
index d112aba8bcfbb6d1ad86862cc157363cbf079a95..0753db817ff10e415340797e13cb17da6b0ae43b 100644 (file)
--- a/libs/freetdm/docs/glare.txt
+++ b/libs/freetdm/docs/glare.txt
@@ -1,29 +1,25 @@
 Glare is a PITA.
 
-Although configuration of ISDN links can be done to minimize glare, to be pedantic we must have a clear policy
+Although configuration of ISDN links can be done to minimize glare, we also must have a clear policy
 on how the FreeTDM API is supposed to behave on glare across signaling modules.
 
-There is a well-known race in the FreeTDM API since the beginning. When a user wants to place a call there is 2 APIs that
-must be used:
+There is a well-known race in the FreeTDM API since the beginning. When a user wants to place a call with
+the old APIs:
 
 1. ftdm_channel_open_xx (to hunt the channel by group, span or select a channel individually)
 2. ftdm_channel_call_place() to place the actual call.
 
 Since the user has no access to channel locking, between opening a channel and placing a call, an incoming call could be
-received. Therefore the user needs to be aware of the following:
+received. Therefore things can get complicated and that is why you should STOP USING those 2 deprecated functions.
 
-1. Between ftdm_channel_open_xx and ftdm_channel_call_place() a SIGEVENT_START can be received, if the user application
-is smart enough, upon receive of SIGEVENT_START it can avoid doing anything else with the channel (from an outgoing call perspective) 
-since that channel is now a channel owned by the incoming call. It can for example hunt another channel using 
-ftdm_channel_open_xx again and avoid calling ftdm_channel_call_place. However, if the app is not smart enough and still calls
-ftdm_channel_call_place even though already received FTDM_SIGEVENT_START on that channel, ftdm_channel_call_place will return
-FTDM_BREAK to inform the user the outgoing call could not be placed and that there is already an incoming call on that channel.
+The replacement is ftdm_call_place().
 
-2. If SIGEVENT_START was not received before calling ftdm_channel_call_place, it could still come while ftdm_channel_call_place()
-is being executed, in such situation ftdm_channel_place_call() will return FTDM_BREAK to inform the user the call could
-not be placed due to glare and the incoming call won the channel, he user should back off since the channel is
-now owned by the incoming call (it can touch the channel having in mind there is now an incoming call on it)
+ftdm_call_place receives the information required to hunt the channel and place the call.
 
-3. After ftdm_channel_call_place returns, if glare is detected and the signaling stack decides to drop the local call, a regular
+If glare is detected after placing the call and the signaling stack decides to drop the local call, a regular
 SIGEVENT_STOP will be sent with the hangup cause FTDM_CAUSE_REQUESTED_CHAN_UNAVAIL.
 
+ftdm_call_place may return FTDM_BREAK if glare is detected while placing the call, in such cases you can try
+calling ftdm_call_place again to hunt another channel.
+
+