Documentation »  ACCESS Linux Platform Native Development »  Telephony Guide »  Telephony Manager

The Telephony Manager provides services which enable applications to perform primary phone activities such as dialing a phone call, sending an SMS, or editing phone book entries.

There are many ways to communicate with phone modules. ACCESS Linux Platform provides a suitable API set and component mechanism to turn telephony-related development efforts into something a wide audience of developers can handle.

Note that, while ACCESS Linux Platform targets the GSM network protocol, the Telephony Manager architecture is built on a modular design to accommodate other network protocols and connection mechanisms, such as those necessary in proprietary or non-AT command solutions.

Telephony Manager Architecture ^TOP^

The Telephony Manager resides as middleware between applications and lower-level ACCESS Linux Platform components. The Telephony Manager relies on the Connection Manager to manage connections through the Data Call and Phone plug-ins.

The following diagram describes the Telephony Manager process:

The Telephony Library is a shared library dedicated to handling telephony services. All Telephony Library functions can be synchronous or asynchronous. In fact, every Telephony Library function relies on a single generic synchronous or asynchronous function, which receives the ID of the message to exchange with the Telephony Server. The interaction between the Telephony Library and applications relies on standard mechanisms: function calls, events and sub-launches.

The Telephony Library is network-independent to the greatest extent possible, and endeavors to deliver the same level of abstraction on every network and phone implementation.

The Telephony Server provides telephony services based on the Telephony Library. Each time an application calls a Telephony Library function, this function call is transparently transformed into a Telephony Message that is sent to the Telephony Server using a Linux socket.

The Telephony Manager contains the following components:

• A shared library (Telephony Library)
• A server (Telephony Server)
• A set of drivers (Network Base Driver, Standard Network Driver, and Phone Specific Driver)
• The Phone Driver UI, a shared library used by the Phone Driver for UI-related activities (e.g. requesting a PIN)
• The Phone Connection Manager Plug-in used to manage the connection between the Telephony Server and the appropriate transport mechanism (see Connection Manager in the Networking Guide)
• The Data Call Connection Manager Plug-in, dedicated specifically to data call connections (see Connection Manager in the Networking Guide)
• The AT commands parser, a shared library that acts as an AT command interpretor

Telephony Manager Features ^TOP^

The Telephony Library is composed of 15 different sets of functions:

Connection (alp_tel_cnc_xxx):

Phone's connection management.

Network (alp_tel_nwk-xxx):

This set of services provides network-oriented services, including authorized networks, forbidden networks, current network, signal level, search mode, etc.

Security (alp_tel_sty_xxx):

The phone and SIM security-related features rely on this set of services. It supports PIN code management.

Power (alp_tel_pow_xxx):

The power supply level can be retrieved through this part of the Telephony Manager. It is also responsible for warning running applications about power shutdown.

Configuration (alp_tel_cfg_xxx):

Phone configuration can be managed using this set of services. It addresses the SMS configuration, etc.

SMS (alp_tel_sms_xxx):

This set of services addresses the Short Message Service (SMS) and enables the caller to read, send, and delete short messages.

Emergency Call (alp_tel_emc_xxx):

Emergency calls are handled through this set of services.

Speech Call (alp_tel_spc_xxx):

Voice calls can be sent and received using this set of services. DTMF are handled in this set of services.

Phone Book (alp_tel_phb_xxx):

The phone's SIM and address book can be accessed through this set of services. It enables the caller to create, view, and delete phone book entries.

Sounds (alp_tel_snd_xxx):

This set of services addresses the phone's sounds management: sound mute, loudspeaker volume, etc.

Information (alp_tel_inf_xxx):

The Information set of services handles phone information. It enables the caller to retrieve information about the current phone.

OEM (alp_tel_oem_xxx):

This set of services provides OEM specific services. It enables hardware manufacturers to extend the Telephony Manager so that it covers desired features. Because OEM services are provided in order to make the Telephony Manager architecture open to phone-specific features, it's not possible to give a list of supported OEM functions (Each manufacturer may provide a specific set of OEM functions for a particular device).

GPRS (alp_tel_gprs_xxx):

This set of functions are used to manage GPRS context.

PS (alp_tel_ps_xxx):

This set of functions are used to manage 3G context.

Card Application Toolkit (alp_tel_cat_xxx):

This set of services addresses the SIM Toolkit service.

For each function or predefined set of functions, a companion function provides its availability in the selected phone/driver/network.

Each function of the Telephony Library can be called synchronously or asynchronously. (Of course, for some of them, only one mode makes sense.)

Synchronous/Asynchronous Calls ^TOP^

Applications that perform activities based on the Telephony Manager can call any function of the Telephony Library synchronously. However, the application blocks after the Telephony function call until the function is finished.

Applications may also call the Telephony Library APIs asynchronously. In this case, the Telephony function call returns directly with a transaction ID which enables the application to identify the response. To retrieve the response, the application registers with the Notify Manager, which performs the callback to provide the asynchronous response.

Notifications ^TOP^

To receive Telephony notifications, applications must register using the Notify Manager API, specifying the appropriate Telephony notification ID. With this feature, an action can be programmed in response to an event or change in status. An application can be launched when network signal strength changes, for example. If the application is already launched, it can be called back in its thread.

For more information about the Notify Manager, see the ACCESS Linux Platform Programming Guide.

You can register to a single Telephony Notification, or to a subset. The following example shows both types of registration.

// Register to a specific notification 
err = alp_notify_register("com.access.apps.myapp",
   ALP_NOTIFY_EVENT_TEL_NWK_SIGNAL_LEVEL, 0, 0); 
 
// Register to all Network notifications 
err = alp_notify_register("com.access.apps.myapp", 
   ALP_NOTIFY_EVENT_TEL_NWK, 0, 0); 
 
// Register to all Telephony notifications 
err = alp_notify_register("com.access.apps.myapp", 
   ALP_NOTIFY_EVENT_TEL, 0, 0); 

For a list of Telephony Manager notifications, see the Telephony module in Doxygen.

Phone Drivers ^TOP^

The Telephony Manager architecture is built on a modular design to accommodate different phone modules. Plug-ins, called Phone Drivers, match the specificities of the phone module. Phone drivers are provided by the licensee who also licenses the hardware.

The Telephony Server use the Package Manager to load/unload Phone Drivers, as in the following example.

Listing 3.1  Loading a Phone Driver

// Init Phone Driver 
{ 
   //! Get Phone Driver package 
   strcpy(driverPackageName, "bar:com.access.phonedriver."); 
   strcat(driverPackageName, iDriverNameP); 
   driverPackage = alp_package_by_name(driverPackageName); 
   if (alp_package_is_NULL(driverPackage)) 
    ... 
 
   //! Get Phone Driver library 
   driverLibrary = alp_package_property_value(driverPackage, 
      "phonedriver", 0, 
      "library"); 
 
   //! Open Phone Driver package 
   *oDriverPackageRefP = alp_package_open(driverPackage); 
 
   //! Get Phone Driver library full path 
     fullPath = 
alp_package_ref_ro_pathname(*oDriverPackageRefP, 
     driverLibrary); 
   
   //! Load Phone Driver library 
   if (!(*oDriverRefNumP = (unsigned long) dlopen(fullPath, 
      RTLD_LAZY))) 
     ... 
 
   //! Call Phone Driver library init function 
   ... 
} 
 
// Cleanup Phone Driver 
{ 
   //! Call Phone Driver library cleanup function 
   ... 
 
   //! Unload Phone Driver library 
   dlclose((void*) iDriverRefNum); 
 
   //! Close Phone Driver package 
   (void) alp_package_close(iDriverPackageRef); 
} 

Error Management ^TOP^

Each Telephony Manager API returns a specific Telephony error. To get information about the error, applications must use alp_tel_err_get_information(). This function returns a string that contains an explanation of the error and a flag to indicate whether this error is related to a problem with the phone profile.

For previous developers, there is one change in the error management: the old function TelUIManage error has been removed. The Telephony Library does not support a UI. If your application requires an error handler that displays a message, the application itself must provide this functionality.

AT Command Parser ^TOP^

The AT command parser (ATCP) provides access to the phone device from a PC via USB, Bluetooth or IrDA in order to perform a data call. This feature provides access to modem functionalities for performing data calls, with no impact on other features.

ATCP Architecture ^TOP^

ATCP is designed as a system library and provides filtering for a limited subset of AT commands. The AT commands shall be parsed and answered by the platform (and not be transparently re-directed to the GSM baseband)

When the application/daemon starts, it loads the ATParser library. While loading, the ATParser library initializes its variables, loads the Telephony Library, and creates a socket to receive AT commands.

In the ATParser library main loop, incoming AT commands are analyzed using lexgen. Any unrecognized commands are ignored (and an UNKNOWN COMMAND error is returned).

ATD Command ^TOP^

The ATD command runs in a specific process. When this command is received, the Connection Manager is called to establish a data call to the phone module, and returns a socket to the library.

Any data received from the application side are forwarded to the telephony file descriptor. These data must be filtered to handle the "+++" or the ATH0 sequence.

The following Connection manager API calls are used:

• alp_cnc_object_find_first()
• alp_cnc_profile_disconnect()
• alp_cnc_object_delete()
• alp_cnc_object_find_close()
• alp_cnc_object_decode()
• alp_cnc_profile_connect()

Supported AT Commands and Result Codes ^TOP^

The following AT commands are supported:

Table 3.1  Standard ATCP Supported AT Commands  

AT Command	Description
&C	Circuit 109 Behavior
&D	Circuit 108 Behavior
&F	Set to factory default
+CGAP	Req. Complete capabilities List
+GMI	Req. Manufacturer Identification
+GMM	Req. Model Identification
+GMR	Req. Revision Identification
A	Answer
D	Dial
E	Command Echo
H	Hook Control
L	Monitor speaker Loudness
M	Monitor speaker Mode
O	Return to online data state
P	Select Pulse dialling
Q	Result code suppression
S0	Automatic answer
S3	Command line termination character
S4	Response formatting character
S5	Command line editing character
S6	Pause before blind dialling
S7	Connection completion timeout
S8	Comma dial modifier time
S10	Automatic disconnect delay
T	Select Tone dialling
V	DCE response format
X	Result Code selection
Z	Reset To default configuration

The following result codes are returned:

Table 3.2  ATCP Result Codes  

The following additional commands are supported, with calls made to the Telephony Library API as shown:

Table 3.3  Additional ATCP Supported AT Commands  

Telephony Manager APIs ^TOP^

The ACCESS Linux Platform SDK includes the reference documentation for those libraries supplied by ACCESS. This documentation can typically be found here:

/opt/alp-dev/sdk/docs/doxygen/index.html

Note that the doxygen directory may not be present. If this is the case, you'll need to extract the contents of the doxygen.zip file that you'll find in the directory /opt/alp-dev/sdk/docs/. Open a terminal window and enter the following commands to extract the ACCESS reference documentation:

cd /opt/alp-dev/sdk/docs 
sudo unzip -d doxygen doxygen.zip 

The Telephony Library must be dynamically linked with applications that use it. The Telephony Server starts using an init script, after the kernel init and before Linux is started. Any required phone drivers are dynamically loaded when needed by the Telephony Server.

The Telephony APIs are divided into three main functional areas:

• Services API
• Notification API
• Errors API

Services API ^TOP^

This API set provides functions, structures, constants, and supporting code for telephony-related functions. Sub-modules include the following:

• Basic: Basic Telephony Services
• Connection: Connection Telephony Services
• Network: Network Telephony Services
• Security: Security Telephony Services
• Power: Power Telephony Services
• Configuration: Configuration Telephony Services
• SMS: SMS Telephony Services
• Emergency Calls: Emergency Calls Telephony Services
• Speech Calls: Speech Calls Telephony Services
• Phone Book: Phone book Telephony Services
• Sound: Sound Telephony Services
• Information: Information Telephony Services
• Packet Switch: Packet Switch Telephony Services
• Card Application Toolkit: Card Application Toolkit Telephony Services
• OEM: OEM Telephony Services

Notification API ^TOP^

This API defines constants related to telephony notification.

Errors API ^TOP^

This API defines constants to identify telephony errors.