A first look on the incoming and idle scripts

In the section called “How does CapiSuite work?” I already told you that there are two kinds of scripts used in CapiSuite. Now let's have a closer look on them.

The incoming script

Every time a call is received by CapiSuite, it will call the incoming script - to be precise it will call a function named callIncoming in a python script located somewhere on your disk. This "somewhere" was defined in the section called “Configuration of CapiSuite”, remember?

So the given script must always define a function with the following signature:

def callIncoming(call,service,call_from,call_to):
	# function body
	...

The parameters given by CapiSuite are:

call

reference to the incoming call. This will be used later in all CapiSuite-functions you call to tell the system which call you mean. You'll only pass this parameter on to other functions - the script can't do anything other with it (it's opaque).

service (integer)

Service of the incoming call as signalled by the ISDN, set to one of the following values:

  • SERVICE_VOICE: voice call

  • SERVICE_FAXG3: analog fax call

  • SERVICE_OTHER: other service not listed above

call_from (string)

the number of the calling party (source of the call) as Python string

call_to (string)

the number of the called party (destination of the call) as Python string

The first task of the function should be to decide if it wants to accept or reject the call. If it accepts it, it will normally do something with it (receive a fax, record a voice call, play nice announcements, ...) and then disconnect. After it has done all necessary work, it should finish immidiately. In a later chapter, I'll present you some examples which should make things clearer.

Naturally, you can break down your application in more functions and perhaps more scripts, which will be called and/or imported recursively - but the starting point is always the incoming script containing callIncoming. If Python and CapiSuite are correctly installed, you should also be able to import and use any Python module.

The idle script

As the incoming script will only be started when a call comes in, we need another mechanism to initiate an outgoing call. As CapiSuite can't know when you plan to do so, it will just call a function named idle in the so called "idle script" in regular intervals. For configuring the intervals and where this script is located, please refer to the section called “Configuration of CapiSuite”.

The called function must have the following signature:

def idle(capi):
	# function body
	...

The only parameter given by CapiSuite is:

capi

This is a reference to an internal class of CapiSuite which handles the communication with the CAPI interface. You'll have to pass on this parameter to some CapiSuite functions. Nothing else useful you can do with it in your script. This parameter has internal reasons and will possibly (hopefully) go away some day in the future. Just pass it on when told to do so for now.

Now you can do what you want in this function. Most likely, you'll check for a job in an email account, look for a file to send in a special directory or so and place a call to send the job to the right destination.

Theoretically, you could also accomplish every other periodical task on your system in the idle script - but perhaps we should leave such general things to applications which were designed for this like cron. ;-)

As above, idle can call other functions or scripts if you like to and all Python modules are available for import.