Main Page | Modules | Class Hierarchy | Alphabetical List | Class List | File List | Class Members | File Members

C/Python wrapper functions

These functions define the python commands you can use in your scripts. More...

Functions

PyObject * capisuite_log (PyObject *, PyObject *args)
 Write an informational message to the CapiSuite log.
PyObject * capisuite_error (PyObject *, PyObject *args)
 Write an error message to the CapiSuite error log.
PyObject * capisuite_audio_send (PyObject *, PyObject *args)
 Send an audio file in a speech mode connection.
PyObject * capisuite_audio_receive (PyObject *, PyObject *args)
 Receive an audio file in a speech mode connection.
PyObject * capisuite_fax_receive (PyObject *, PyObject *args)
 Receive a fax in a fax mode connection.
PyObject * capisuite_fax_send (PyObject *, PyObject *args)
 Send a fax in a fax mode connection.
PyObject * capisuite_disconnect (PyObject *, PyObject *args)
 Disconnect connection.
PyObject * capisuite_reject (PyObject *, PyObject *args)
 Reject an incoming call.
PyObject * capisuite_connect_voice (PyObject *, PyObject *args)
 Accept an incoming call and connect with voice service.
PyObject * capisuite_connect_faxG3 (PyObject *, PyObject *args)
 Accept an incoming call and connect with fax (analog, group 3) service.
PyObject * capisuite_call_voice (PyObject *, PyObject *args)
 Initiate an outgoing call with service voice and wait for successful connection.
PyObject * capisuite_call_faxG3 (PyObject *, PyObject *args)
 Initiate an outgoing call with service faxG3 and wait for successful connection.
PyObject * capisuite_switch_to_faxG3 (PyObject *, PyObject *args)
 Switch a connection from voice mode to fax mode.
PyObject * capisuite_enable_DTMF (PyObject *, PyObject *args)
 Enable recognition of DTMF tones.
PyObject * capisuite_disable_DTMF (PyObject *, PyObject *args)
 Disable recognition of DTMF tones.
PyObject * capisuite_read_DTMF (PyObject *, PyObject *args)
 Read the received DTMF tones or wait for a certain amount of them.

Detailed Description

These functions define the python commands you can use in your scripts.

All CapiSuite-commands available in Python will stay in a python module called capisuite. This module and all its functions are defined here.

There's a general scheme for mapping the names of the C wrapper functions to python names:

Python command "capisuite.command()" will be defined in the wrapper function "capisuite_command()".

So you can use this document as reference to all available CapiSuite Python commands. For example, if you read the documentation for the capisuite_audio_send function here, you can use it as capisuite.audio_send in your Python scripts.


Function Documentation

PyObject* capisuite_audio_receive PyObject *  ,
PyObject *  args
[static]
 

Receive an audio file in a speech mode connection.

This functions receives an audio file. It can recognize silence in the signal and timeout after a given period of silence, after a general timeout or after the reception of a DTMF signal.

If the recording was finished because of silence_timeout, the silence will be truncated away.

If DTMF abort is enabled, the command will also abort immediately if DTMF was received before it is called. That allows you to abort subsequent audio receive and send commands with one DTMF signal w/o needing to check for received DTMF after each command.

The connction must be in audio mode (use capisuite_connect_voice()), otherwise an exception will be caused.

The created file will be saved in bit-reversed A-Law format, 8 kHz mono. Use sox to convert it to a normal wav file.

Parameters:
args Contains the python parameters. These are:
  • call Reference to the current call
  • filename (string) where to save received file
  • timeout (integer) receive length in seconds (-1 = infinite)
  • silence_timeout (integer, optional) abort after x seconds of silence (0=off, default)
  • exit_DTMF (integer, optional) if set to 1, sending is aborted when a DTMF signal is received (0=off, default)
Returns:
int containing duration of receive in seconds

PyObject* capisuite_audio_send PyObject *  ,
PyObject *  args
[static]
 

Send an audio file in a speech mode connection.

This function sends an audio file. The audio file must be in bit-inversed A-Law format. It can be created for example with sox using the suffix ".la". It supports abortion if DTMF signal is received.

If DTMF abort is enabled, the command will also abort immediately if DTMF was received before it is called. That allows you to abort subsequent audio receive and send commands with one DTMF signal w/o needing to check for received DTMF after each command.

The connction must be in audio mode (use capisuite_connect_voice()), otherwise an exception will be caused.

Parameters:
args Contains the python parameters. These are:
  • call Reference to the current call
  • filename (string) file to send
  • exit_DTMF (integer, optional) if set to 1, sending is aborted when a DTMF signal is received (0=off, default)
Returns:
int containing duration of send in seconds

PyObject* capisuite_call_faxG3 PyObject *  ,
PyObject *  args
[static]
 

Initiate an outgoing call with service faxG3 and wait for successful connection.

This will initiate an outgoing call and choose fax group 3 as service, so you can use the fax commands (like fax_send and fax_receive) with this connection. After this command has finished, the call is connected successfully or the given timeout has exceeded. The timeout is measured beginning at the moment when the call is signalled (it's "ringing") to the called party.

A python tuple (call,result) is returned by this function. It contains:

  • call reference to the created call object - use this for subsequent calls like audio_send
  • result (int) result of the call establishment process.
    • 0 = connection established
    • 1 = connection timeout exceeded, no connection was established
    • 2 = connection wasn't successful and no reason for this failure is available
    • 0x3301-0x34FF: Error reported by CAPI. For a complete description see the annex of the user manual

Parameters:
args Contains the python parameters. These are:
  • capi reference to object of Capi to use (given to the idle function as parameter)
  • controller (int) ISDN controller ID to use
  • call_from (string)own number to use
  • call_to (string)the number to call
  • timeout (int)timeout to wait for connection establishment in seconds
  • faxStationID (string)fax station ID
  • faxHeadline (string) fax headline to print on every page
  • clir (int, optional)set to 1 to disable sending of own number (0=default)
Returns:
tuple (call,result) - see above.

PyObject* capisuite_call_voice PyObject *  ,
PyObject *  args
[static]
 

Initiate an outgoing call with service voice and wait for successful connection.

This will initiate an outgoing call and choose voice as service, so you can use the audio commands (like audio_receive and audio_send) with this connection. After this command has finished, the call is connected successfully or the given timeout has exceeded. The timeout is measured beginning at the moment when the call is signalled (it's "ringing") to the called party.

A python tuple (call,result) is returned by this function. It contains:

  • call reference to the created call object - use this for subsequent calls like audio_send
  • result (int) result of the call establishment process.
    • 0 = connection established
    • 1 = connection timeout exceeded, no connection was established
    • 2 = connection wasn't successful and no reason for this failure is available
    • 0x3301-0x34FF: Error reported by CAPI. For a complete description see the annex of the user manual

Parameters:
args Contains the python parameters. These are:
  • capi reference to object of Capi to use (given to the idle function as parameter)
  • controller (int) ISDN controller ID to use
  • call_from (string)own number to use
  • call_to (string)the number to call
  • timeout (int)timeout to wait for connection establishment in seconds
  • clir (int, optional)set to 1 to disable sending of own number (0=default)
Returns:
tuple (call,result) - see above.

PyObject* capisuite_connect_faxG3 PyObject *  ,
PyObject *  args
[static]
 

Accept an incoming call and connect with fax (analog, group 3) service.

This will accept an incoming call and choose fax group 3 as service, so you can use the fax commands (like fax_receive) with this connection. After this command has finished, the call is connected successfully.

It's also possible to accept a call with some delay. This is for example useful if you want to have the chance to get a call with your phone before your computer answers it.

Parameters:
args Contains the python parameters. These are:
  • call Reference to the current call
  • faxStationID (string) the station ID to use
  • faxHeadline (string) the fax headline to use
  • delay (integer, optional) delay in seconds _before_ connection will be established (default: 0=immediate connect)
Returns:
If faxInfo is available, a tuple (stationID,rate,hiRes,format) otherwise None. Tuple contains:
  • fax station ID from the calling party (String)
  • bit rate which was used for connecting
  • high (1) or low (0) resolution
  • transmit format: 0=SFF,black&white, 1=ColorJPEG

PyObject* capisuite_connect_voice PyObject *  ,
PyObject *  args
[static]
 

Accept an incoming call and connect with voice service.

This will accept an incoming call and choose voice as service, so you can use the audio commands (like audio_receive and audio_send) with this connection. After this command has finished, the call is connected successfully.

It's also possible to accept a call with some delay. This is for example useful for an answering machine if you want to have the chance to get a call with your phone before your computer answers it.

Parameters:
args Contains the python parameters. These are:
  • call Reference to the current call
  • delay (integer, optional) delay in seconds _before_ connection will be established (default: 0=immediate connect)
Returns:
None

PyObject* capisuite_disable_DTMF PyObject *  ,
PyObject *  args
[static]
 

Disable recognition of DTMF tones.

You can disable the recognition of DTMF tones again if you want to.

Parameters:
args Contains the python parameters. These are:
  • call Reference to the current call
Returns:
None

PyObject* capisuite_disconnect PyObject *  ,
PyObject *  args
[static]
 

Disconnect connection.

This will cause an immediate disconnection. It should be always the last command in every flow of a script. It will return a tuple of two result values. The first is the disconnect cause of the physical connection, the second the disconnect cause of the logical connection. See CAPI spec for the logical causes and ETS 300 102-01 for the physical causes.

Parameters:
args Contains the python parameters. These are:
  • call Reference to the current call
Returns:
Tuple containing (ReasonPhysical,ReasonLogical)

PyObject* capisuite_enable_DTMF PyObject *  ,
PyObject *  args
[static]
 

Enable recognition of DTMF tones.

You have to enable the recognition of DTMF tones if you want to use them in your script.

Parameters:
args Contains the python parameters. These are:
  • call Reference to the current call
Returns:
None

PyObject* capisuite_error PyObject *  ,
PyObject *  args
[static]
 

Write an error message to the CapiSuite error log.

This function writes a message to the CapiSuite error log. It should be used to output error messages so they appear in the normal error log.

Parameters:
args Contains the python parameter:
  • message (string) the log message
Returns:
None

PyObject* capisuite_fax_receive PyObject *  ,
PyObject *  args
[static]
 

Receive a fax in a fax mode connection.

This command receives an analog fax (fax group 3). It starts the reception and waits for the end of the connection. So it should be the last command before capisuite_disconnect.

The connction must be in fax mode (use capisuite_connect_faxG3 or capisuite_switch_to_faxG3), otherwise an exception will be caused.

The created file will be saved in the Structured Fax File (SFF) format.

Parameters:
args Contains the python parameters. These are:
  • call Reference to the current call
  • filename (string) where to save received fax
Returns:
None

PyObject* capisuite_fax_send PyObject *  ,
PyObject *  args
[static]
 

Send a fax in a fax mode connection.

This command sends an analog fax (fax group 3). It starts the send and waits for the end of the connection. So it should be the last command before capisuite_disconnect.

The connction must be in fax mode (use capisuite_call_faxG3 or capisuite_switch_to_faxG3), otherwise an exception will be caused.

The created file will be saved in the Structured Fax File (SFF) format.

Parameters:
args Contains the python parameters. These are:
  • call Reference to the current call
  • filename (string) file to send
Returns:
None

PyObject* capisuite_log PyObject *  ,
PyObject *  args
[static]
 

Write an informational message to the CapiSuite log.

This function writes a message to the CapiSuite log. It's helpful if you want to write messages in the debug log in your scripts.

The message can be either logged with the general CapiSuite prefix if they are of global nature or with the Connection prefix if they're associated with a special connection.

Parameters:
args Contains the python parameters. These are:
  • message (string) the log message
  • level (integer) parameter for log_level
  • call (optional) call reference - if given, the message is logged with Connection prefix
Returns:
None

PyObject* capisuite_read_DTMF PyObject *  ,
PyObject *  args
[static]
 

Read the received DTMF tones or wait for a certain amount of them.

This function allows to just read in the DTMF tones which were already received. But it also supports to wait for a certain amount of DTMF tones if you want the user to always input some digits at a certain step in your script.

You can specify how much DTMF tones you want in several ways - see the parameter description. To just see if something was entered before, use capisuite.read_DTMF(0). If you want to get at least 1 and mostly 4 digits and want to wait 5 seconds for additional digits, you'll use capisuite.read_DTMF(5,1,4).

Valid DTMF characters are '0'...'9','A'...'D' and two special fax tones: 'X' (CNG), 'Y' (CED)

Parameters:
args Contains the python parameters. These are:
  • call Reference to the current call
  • timeout (integer) timeout in seconds after which reading is terminated, only applied when min_digits are reached! (-1 = infinite)
  • min_digits (integer, optional) minimum number of digits which must be read in ANY case, i.e. timout doesn't count here (default: 0)
  • max_digits (integer, optional) maximum number of digits to read (aborts immediately if this number is reached) (0=infinite, i.e. only timeout counts, default)
Returns:
python string containing the received DTMF characters

PyObject* capisuite_reject PyObject *  ,
PyObject *  args
[static]
 

Reject an incoming call.

If you don't want to accept an incoming call for any reason (e.g. if it has a service or comes from a number you don't want to accept), use this command. There are several reasons you can give when rejecting a call. Some important ones are:

  • 1=ignore call
  • 2=normal call clearing
  • 3=user busy
  • 7=incompatible destination
  • 8=destination out of order
  • 0x34A9=temporary failure

You can find many more reasons in the ETS 300 201-01 specification or on the web (search for ISDN cause) if you really need them.

Parameters:
args Contains the python parameters. These are:
  • call Reference to the current call
  • rejectCause (integer) which cause to signal when rejecting call (see above)
Returns:
None

PyObject* capisuite_switch_to_faxG3 PyObject *  ,
PyObject *  args
[static]
 

Switch a connection from voice mode to fax mode.

This will switch from voice mode to fax group 3 after you have connected, so you can use the fax commands afterwards.

Attention: This command isn't supported by every ISDN card / CAPI driver!

Parameters:
args Contains the python parameters. These are:
  • call Reference to the current call
  • faxStationID (string) the station ID to use
  • faxHeadline (string) the fax headline to use
Returns:
If faxInfo is available, a tuple (stationID,rate,hiRes,format) otherwise None. Tuple contains:
  • fax station ID from the calling party (String)
  • bit rate which was used for connecting
  • high (1) or low (0) resolution
  • transmit format: 0=SFF,black&white, 1=ColorJPEG


Generated on Sun Nov 28 14:37:45 2004 for CapiSuite by doxygen 1.3.8