DESCRIPTION
-----------

SIP prepaid functionality is achieved by:

1. An external call control module (not provided by CDRTool) that maintains
call status and terminates calls by sending BYEs to both SIP end-points. The
call control module communicates with both the SIP Proxy and CDRTool using
an API described below. 

2. CDRTool rating engine - provides session locking, calculates maximum
session time based on user balance and destination using the same algorithm
as the postpaid engine and debits the subscriber balance.

See doc/PrepaidEngine.pdf for a detailed call flow.


Prepaid API
-----------

CDRTool prepaid engine is used to compute session times based on user credit
and destination rates and debit the balance when the call has ended. The
prepaid engine is accessible over a TCP socket.

Call control module sends commands based on the syntax described below, to
the CDRTool prepaid engine that handles the prepaid accounts. A command is a
line of text containing a keyword, which is the command itself followed by a
number of parameters separated by space. The command ends with an enter in
unix style: '\n' For each such request there will be a reply on one or more
lines, containing information that depends on the command that was sent. A
reply ends when a double end of line (\n) is received: \n\n (this is needed
because there are commands that require multiline responses). How the
information contained in a reply is to be interpreted depends on the command
itself and is described below.


1. Asking for the call time limit
   ------------------------------

To request the maximum time for a session, the following request must be
sent to CDRTool rating engine on one line:

MaxSessionTime From=sip:123@example.com To=sip:0031650222@example.com
Duration=7200 Gateway=81.20.68.10 ENUMtl=tld.com Lock=1\n

Duration is a limit imposed to the time allowed, in case you want to limit
the call time to a maximum duration. This will be a top limit for the call's
time, even if the user could talk more than that based on his current
balance. The SIP proxy may limit all calls to 7200 seconds for example. 
Lock specifies if the account is to be locked or not (i.e. don't allow the
same user make multiple calls at the same time). This is used because
sometimes we only need to peek at the time but not actually start a call and
lock the user. When the call starts the account should always be locked. To
may actually be sip:number@domain;param=value so you must extract the
username part which is the number From is a sip URI which can be "full name"

ENUMtld parameter is optional but if present discounts based on ENUM can be
applied (see RATING.txt for more information on ENUM discounts).

Call control expects a reply like below:

value\n\n

value is the numeric time in seconds, or one of the keywords Locked or None
(None meaning it's not a prepaid account and it doesn't have any limitation,
or it's a free destination, like a 0800... number).  There is no empty line
before value (response starts with value on the first line and then it has 2
enters unix style as described).

To field must be the canonical destination SIP URI after all possible
lookups in the SIP Proxy.

2. Debiting the balance when the conversation ends
   -----------------------------------------------

To debit money from the user account when the conversation ends, the Call
control module must send the following command on one line:

DebitBalance From=sip:123@example.com To=sip:0031650222@example.com
Gateway=81.20.68.10 Duration=59\n

Same notes about the From and To fields as above apply.

and expects in return:

value\n\n

where value is one of: OK (success), Failed (failure), NotPrepaid (account
is not prepaid - this case is not considered a failure)

There are cases where we call DebitBalance with a 0 duration. This is valid
and should unlock the account but leave the credit untouched.


Prepaid calls in progress
-------------------------

To see the calls in progress go to Rating -> Prepaid -> Search with Lock = 1

If the connection between the SIP Proxy call control module and CDRTool
rating engine is broken it is possible to have prepaid accounts that
remained locked because no DebitBalance command has been received. To unlock
these accounts find them in Rating -> Prepaid section and set Lock to 0.


Third party tools
-----------------

FreeRADIUS-CDRTool by Dan-Cristian Bogos 

FreeRADIUS module providing connectivity to CDRTool prepaid engine. Provides
prepaid authentication for calls proxied by OpenSER and returns to OpenSER
MaxCallDuration and user Credit. Can be easily extended to support other SIP
or H323 devices.

http://sourceforge.net/projects/frad-cdrtool


Notes
-----

The balance is debited correctly regardless of the moment of CDR
normalization. Renormalization of calls do not recalculate balance.

By default only one call at a time can be performed using a prepaid account.
You may enable multiple parallel calls using the same prepaid call if you
accept the idea that the balance might become negative. For this set in
global.inc $RatingEngine['prepaid_lock'] to false.
