.. _module-telephony:

Telephony
--------------------------

* **Identifier** - TELEPHONY
* **Description** - Allows to control basic device features.
* **Initialization** - Looks for availability of mobile phone hardware (GSM).
* **Destroy** - None
* **Dependencies** - :ref:`module-core`, :ref:`module-contacts`

Value Types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cssclass:: table-bordered

+-----------------------+----------------------------------------------------------+---------------+----------------------------+
| Name                  | Description                                              | From Version  | Wrapper Class              |
+=======================+==========================================================+===============+============================+
| **SIGNAL-STRENGTH**   | Represents signal strength.                              | 1             | VT_SignalStrength_Wrapper  |
+-----------------------+----------------------------------------------------------+---------------+----------------------------+

Trigger Ringing
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Name         | RINGING                                                                                                |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Description  | Executes when device is ringing for an incoming call.                                                  |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
|              | Type                            | Name                 | Required     | Description                    |
+==============+=================================+======================+==============+================================+
| Parameters   | CONTACTS.PHONE-NUMBER           | PHONE-NUMBER         | No           | If present, trigger is         |
|              |                                 |                      |              | executed only if caller number |
|              |                                 |                      |              | matches with provided one.     |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Variables    | CONTACTS.PHONE-NUMBER           | PHONE-NUMBER                        | Eventual caller number,        |
|              |                                 |                                     | otherwise *null*.              |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

Trigger Offhook
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Name         | OFFHOOK                                                                                                |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Description  | Executes when a call starts.                                                                           |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

Trigger Idle
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Name         | IDLE                                                                                                   |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Description  | Executes when device, after a call, comes back to idle status.                                         |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

Trigger Signal Strength
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Name         | SIGNAL-STRENGHT                                                                                        |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Description  | Executes when GSM signal strength changes.                                                             |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
|              | Type                            | Name                                | Description                    |
+==============+=================================+======================+==============+================================+
| Variables    | TELEPHONY.SIGNAL-STRENGTH       | STRENGHT                            | Detected signal strength       |
|              |                                 |                                     | when trigger executes          |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

Performer Answer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Name         | ANSWER                                                                                                 |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Description  | Answer to an incoming call (so it can only work in case there is an incoming call).                    |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

Performer Reject
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Name         | REJECT                                                                                                 |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Description  | Reject an incoming call (so it can only work in case there is an incoming call).                       |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

Performer Mute
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Name         | MUTE                                                                                                   |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Description  | Set mute to an incoming call (so it can only work in case there is an incoming call).                  |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

Performer Call Number
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Name         | CALL-PHONE-NUMBER                                                                                      |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Description  | Make a call to a provided number.                                                                      |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
|              | Type                            | Name                 | Required     | Description                    |
+==============+=================================+======================+==============+================================+
| Parameters   | CONTACTS.PHONE-NUMBER           | PHONE-NUMBER         | Yes          | Number to call.                |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

Performer End Call
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Name         | END-CALL                                                                                               |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Description  | Terminate a call.                                                                                      |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

Performer Voice Volume
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Name         | VOICE-VOLUME                                                                                           |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Description  | Set voice volume for calls.                                                                            |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
|              | Type                            | Name                 | Required     | Description                    |
+==============+=================================+======================+==============+================================+
| Parameters   | CORE.PERCENT                    | VOLUME               | Yes          | Volume percent value.          |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

Performer Ringer Volume
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Name         | RINGER-VOLUME                                                                                          |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+
| Description  | Set ringer volume.                                                                                     |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+

.. cssclass:: table-bordered

+--------------+---------------------------------+----------------------+--------------+--------------------------------+
|              | Type                            | Name                 | Required     | Description                    |
+==============+=================================+======================+==============+================================+
| Parameters   | CORE.PERCENT                    | VOLUME               | Yes          | Volume percent value.          |
+--------------+---------------------------------+----------------------+--------------+--------------------------------+