Documentation »  ACCESS Linux Platform Native Development »  Telephony Guide »  Programming Telephony Applications

Mobile Services exposes a set of C structures and functions that provide actual access to services, as well as callback function prototypes that must be implemented by applications in order to respond to notifications.

Virtual Phone ^TOP^

In order to aid in phone application development, the ACCESS Linux Platform SDK provides Virtual Phone 2, a Windows application that simulates a cellular phone environment.

For details about Virtual Phone, see the Virtual Phone 2 Guide.

Mobile Services APIs ^TOP^

The following diagram presents an overview of the different objects provided by the Mobile Services, and their related APIs.

Mobile

This service provides access to the available Mobile Context. It also gives access to an aggregated view of the current calls and call history. The Mobile service API provides twelve functions to access and manage this information.

Mobile Context

This service defines a Mobile Context. A Mobile Context contains basic information about the network, operator, and phone, and its functions manage normal phone calls (incoming, outgoing, and history) as well as emergency calls, and provide call status. The implementation component may also offer complementary services through other interfaces. For instance the Cellular Mobile Context service also implements the Network service. Amongst the available contexts, one is called the default context.

Several contexts may be available on the same device. Some are connected to a cellular mobile network, such as GSM, and others are more virtual, like SIP. A Mobile Context implements a notifications mechanism through the IMobileContextEventSource interface.

Network

This service provides access to information about a mobile network, including status, signal strength, and network time, as well as access to an operator.

For now, only the Cellular Mobile Context implements a Network service.

Operator

This service provides access to information about an operator, including name, identification number, and APN. This service may eventually provide access to an operator's logo.

Call

This service provides functions that enable a phone call, including dialing an outgoing call, accepting/rejecting incoming calls, and accessing call statistics such as duration. All basic calling activities are accessed through the Call service.

Speed Dial

This service provides support for Speed Dial functionality. Applications can assign numbers to hard keys, manage them, and dial them.

Speed Dial information is stored in an SQLite 3 database called mobile_speed_dial.sql and formatted as:

Key, INTEGER 
DialNumber, STRING 
Lock, INTEGER  

This database may be present in ROM. If the database is not available, Mobile Services creates the database file and the table without any specified values. If an operator want a pre-defined value, they must add a database with its value in ROM.

There is a lock mechanism. If an entry has its 'Lock' value set, an application can not change its value. There is no API to turn on or off the lock value—any entry added using the Speed Dial API is unlocked. The only way to have a locked entry is to have a database in ROM.

Audio

This service set provides access to audio functionality, particularly the audio portion of a phone call. Applications have access to available devices, usually the internal speaker and/or Bluetooth HeadSet/HandsFree devices if present.

Include Files and Shared Libraries ^TOP^

You must include the Mobile Services header files in your application in order to use Mobile Services. To include all header files at once, use:

#include <alp/mobile_overall.h> 

You can also include each individual Mobile Services header file as needed, although some header files also include others. For example, alp/mobile.h also includes alp/mobile_context.h, alp/mobile_call.h, and alp/mobile_services.h.

You must also compile your application with the alp_mobile shared library in order to link your application to Mobile Services. To link with Exchange Manager and the Contacts database, you must compile with alp_exgmgr and alp_contacts_dml, respectively.

Programming Examples ^TOP^

For details about the functions, constants, prototypes, and data structures shown in the following examples, see the API reference documentation.

Note that the following examples are shown in logical order.

Getting a Mobile Context ^TOP^

Use the Mobile API to obtain access to an existing Mobile Context.

The standard method is to get the default Mobile Context using alp_mbl_get_default_context(), which sets a pointer to an AlpMblContextId object with the default Mobile Context's ID. If there is no default context, the object contains the value ALP_MBL_CONTEXT_INVALID_CONTEXT_ID.

AlpMblContextId context_id;
alp_mbl_get_default_context(&context_id); 

In ACCESS Linux Platform 1.0, the Cellular Mobile Context is provided.

Getting Network Status and Signal Level ^TOP^

Once an application has a Mobile Context, a likely first action is to check the network status and signal level. This is done by using the Mobile Context ID to access the Network service. The network technology is also returned. Note that the Cellular Mobile Context is used.

AlpMblContextId   context_id; 
AlpMblNetworkId   network_id; 
AlpMblNetworkStatus  network_status; 
AlpMblNetworkAccessTechnology  network_technology; 
AlpMblNetworkSignalLevel  network_signal_level; 
 
// Get the default context 
alp_mbl_get_default_context(&context_id); 
 
// Get the network id associated with this mobile context 
alp_mbl_context_get_network_id(context_id, &network_id); 
 
// Get network info 
alp_mbl_network_get_status(network_id,	&network_status, 
   &network_technology); 
 
// Get signal level 
alp_mbl_network_get_signal_level(network_id, 
&network_signal_level); 

Making a Phone Call ^TOP^

In order to initiate or receive a phone call, an application must first get a Mobile Context (see "Getting a Mobile Context", above), and then invoke alp_mbl_context_new_call(). The address parameter indicates the phone number to call. The call ID is returned to enable a user to retrieve call information.

AlpMblAddress     dial_address; 
AlpMblCallId      call_id; 
 
// Get the default context 
alp_mbl_get_default_context(&context_id); 
 
// Dial address 
alp_mbl_context_new_call (context_id, dial_address, &call_id)  

Making an Emergency Call ^TOP^

Making an emergency call is very similar to making a normal call except that an address is not needed:

AlpMblCallId      call_id; 
 
// Get the default context 
alp_mbl_get_default_context(&context_id); 
 
// Dial emergency call 
alp_mbl_context_new_emergency_call (context_id, &call_id)  

To check whether a current call is an emergency call, use the following example. The Boolean output parameter is_emergency is true if the call is an emergency call.

AlpMblCallId    call_id;  
bool            is_emergency; 
 
// Check whether current call is emergency  
alp_mbl_call_is_emergency_call (call_id, &is_emergency); 
 
if (is_emergency) ... 

Assigning and Dialing a Speed Dial Contact ^TOP^

This example shows how to add a contact to the speed dial database. The variable contact_luid indicates the LUID of a contact in the Contacts database. This function returns the index where the entry has been added. For more information, see the reference documentation for Contacts Data Model in the Application Libraries documentation module.

AlpLuid  contact_luid; 
AlpMblSpeedDialIndex      sd_new_index; 
 
//assign contact_luid to new index 
alp_mbl_speed_dial_add (contact_luid, &sd_new_index); 

This example shows how to dial a Speed Dial contact:

AlpSpeedDialList     speedDialList; 
AlpMblCallId         call_id; 
 
//  Get speed dial list  
alp_mbl_speed_dial_get_list(&speedDialList);  
 
//  Dial speed dial entry 5 
 
alp_mbl_speed_dial_dial(speedDialList .listP[5].contactLuid,  
   &call_id);  
 
//deallocate memory 
alp_mbl_free(speedDialList .listP); 

Getting Call History ^TOP^

A Mobile Context contains a history of the calls made in that context. The history is maintained as a list. The type of history can be limited using the following constants as the first argument to alp_mbl_get_call_history_count():

This example shows the retrieval of the number of missed calls:

int hist_count = 0; 
alp_mbl_get_call_history_count(
    ALP_MBL_CALL_HISTORY_TYPE_MISSED, &hist_count); 

This example shows the retrieval of all recent calls. Note that the memory allocated for the history must be freed using alp_mbl_free().

AlpMblCallHistoryList hist_list; 
 
//retreive the list 
alp_mbl_get_call_history( 
   ALP_MBL_CALL_HISTORY_TYPE_RECENT,  
   0, 
   hist_count - 1, 
   &hist_list); 
 
// do something useful with the list 
unsigned int i; 
for (i=0; i <= hist_count; i++) {...} 
 
//deallocate memory 
alp_mbl_free(hist_list); 

Looking at Phone Specifics ^TOP^

The Cellular Mobile Context contains phone-specific information, including the manufacturer, model, revision, and serial number. The Connection Manager profile ID is also available using this API.

AlpMblContextId        context_id; 
 
AlpMblContextCellManufacturer   manufacturer; 
AlpMblContextCellModel       model; 
AlpMblContextCellRevision    revision; 
AlpMblContextCellMobileId    mobile_id; 
 
alp_mbl_get_default_context(&context_id); 
 
//retrieve phone-specific information using context ID 
alp_mbl_context_cell_get_manufacturer(context_id,  
    &manufacturer); 
alp_mbl_context_cell_get_model(context_id, &model); 
alp_mbl_context_cell_get_revision(context_id, &revision); 
alp_mbl_context_cell_get_mobile_id(context_id, &mobile_id); 
 
//get connection manager profile id 
AlpMblCncProfileId cnc_profile_id; 
alp_mbl_context_cell_get_cnc_profile_id(context_id, 
    &cnc_profile_id); 

Retrieving Carrier Network Information ^TOP^

A network can have more than one operator. Use the Network API to retrieve operator information for the carrier network specified by the current Mobile Context. You can also use this API to set an operator for the context.

AlpMblContextId    context_id; 
AlpMblNetworkId    network_id; 
AlpMblOperatorList  *op_list; 
AlpMblOperatorId    *operator_id; 
 
// Get the network id of the current context 
alp_mbl_context_get_network_id(context_id, &network_id); 
 
//get operator info for current network 
alp_mbl_network_get_available_operators(network_id, 
   &op_list); 
alp_mbl_network_get_operator(network_id, &operator_id); 
 
//set operator for current network 
alp_mbl_network_set_operator(network_id, operator_id); 

Retrieving Operator/Carrier Information ^TOP^

First use the Mobile Context API to retrieve the operator ID, and then use that ID to retrieve operator information using the Operator API.

AlpMblContextId     context_id; 
AlpMblOperatorId    operator_id; 
 
alp_mbl_get_default_context(&context_id); 
 
//retrieve operator ID 
alp_mbl_context_get_home_operator_id (context_id, 
    &operator_id); 
 
//retrieve operator information 
AlpMblOperatorName     op_name; 
AlpMblOperatorNumber   op_number; 
AlpMblOperatorApn      op_apn; 
 
alp_mbl_operator_get_name(operator_id, &op_name); 
alp_mbl_operator_get_number(operator_id, &op_number); 
alp_mbl_operator_get_apn(operator_id, &op_apn); 

Looking at SIM Card ^TOP^

SIM card information can be viewed with USIM. See "USIM API."

Receiving Notifications ^TOP^

Applications can set observers to watch for notifications using the Mobile API. In this example, a private function creates an observer to watch for signal level changes, and provides a hook to create an error handler.

GMainContext*    sGLibContextP; 
AlpMblNetworkSignalLevel     sNetworkSignalLevel; 
 
void prv_signal_level_change(AlpMblNetworkId iNetworkId, 
          AlpMblNetworkSignalLevel iPrevious,  
          AlpMblNetworkSignalLevel iCurrent) 
{ 
  // Store new value 
  sNetworkSignalLevel = iCurrent; 
 
  // Update signal level icon 
  prv_update_signal_level_icon(sNetworkSignalLevel); 
} 
 
void prv_init_mobile_observers() 
{ 
              AlpMblObserver  myObservers[2]; 
              alp_status_t    err; 
 
   myObservers[0].serviceId = ALP_MBL_NETWORK_SERVICE_ID; 
   myObservers[0].notificationId =  
      ALP_MBL_NWK_SIGNAL_LEVEL_CHANGE_NOTIFICATION; 
   myObservers[0].callbackP = prv_signal_level_change; 
   myObservers[0].userDataP = NULL; 
 
   myObservers[1].serviceId = ALP_MBL_NO_SERVICE_ID; 
 
   if ((err = alp_mbl_add_observers(NULL, myObservers)) !=  
        ALP_STATUS_OK) 
  {    // Error management 
     return; 
  } 
 
} 

USIM API ^TOP^

USIM Application Management

To get the default USIM application identifier.

alp_status_t	alp_mbl_usim_get_default_usim_id	(AlpMblUsimId*
oDefaultUsimIdP); 

If the card supports only one USIM application, the default usimId is equal to one.

In a multi-application environment, the default usimId is the identifier of the last active USIM.

To get the list of USIM application identifier if several USIMs are stored in the UICC:

alp_status_t	alp_mbl_usim_get_usim_ids		(AlpMblUsimList* 
oUsimListP); 

To select the active USIM amongst those available on the UICC:

alp_status_t	alp_mbl_usim_select_usim_id		(AlpMblContextId 
iMobileContextId, AlpMblUsimId iUsimId); 

MSISDN selection

To get the MSISDN numbers stored in the card:

alp_status_t	alp_mbl_usim_get_msisdn_numbers		(AlpMblMsisdnList* 
oMsisdnNumbersListP); 

To get the active MSISDN number:

alp_status_t	alp_mbl_usim_get_current_msisdn_number
(AlpMblMsisdn* oMsisdnNumberP); 

To select the MSISDN number amongst those available on the UICC:

alp_status_t	alp_mbl_usim_select_msisdn_number	(AlpMblMsisdn* 
iMsisdnNumberP); 

User Profile Selection

To retrieve a user profile list:

alp_status_t	alp_mbl_usim_get_user_profiles
(AlpMblUserProfileList* oUserProfileListP); 

To select a user profile:

alp_status_t	alp_mbl_usim_select_user_profile
(AlpMblUserProfile* iUserProfileP); 

File management

alp_status_t	alp_mbl_usim_get_card_file   (AlpMblUsimId 
iUsimId, AlpMblUsimCardFile* ioCardFileP); 

As this API could take some times (especially when accessing data), the function will return ALP_STATUS_MBL_VALUE_NOT_AVAILABLE, and the information will be returned using the notification mechanism.

According the mode indicated in the 'AlpMblUsimCardFile' structure, it is possible to get File information or to access EF data with absolute or relative addressing.

To identify the file, the file Id can only be used but in case of ambiguous files identifiers, the full path Id can be used to indicate the targeted UICC directory path.

Notifications

A STK Application shall register to the Mobile Services:

• to get notifications of Elementary Files results (asynchronous answer for the alp_mbl_usim_get_card_file API)
• to get notifications of USIMid change
• to get notifications when EFs have been changed (in structure or contents). If there is an image of EFs in the terminal memory, the terminal shall update this image.
• to get notifications when the UICC is reset

To handle EF result notifications, the application shall supply and implement a callback function accordingly the following typedef prototype:

typedef void	(*AlpMblUsimGetCardFileResultCallbackPtr)
(AlpMblUsimCardFile* CardFileP);  

To handle USIMid change notifications, the application shall supply and implement a callback function accordingly the following typedef prototype:

typedef void	(*AlpMblUsimIdChangeCallbackPtr) (AlpMblContextId
iMobileContextId, AlpMblUsimId iPrevious, AlpMblUsimId 
iCurrent); 

To handle EFs change notifications, the application shall supply and implement a callback function accordingly the following typedef prototype:

typedef void	(*AlpMblUsimFileChangeCallbackPtr) 
(AlpMblUsatRefreshFileList* ioFileListP); 

To handle Session reset notifications, the application shall supply and implement a callback function accordingly the following typedef prototype:

typedef void	(*AlpMblUsimSessionResetCallbackPtr)	 (void); 

Memory Management

Applications should use alp_mbl_free to free the AlpMblUsimCardFile structure given in the EF result callback when the EF result is fully handled. Also, the application should use alp_mbl_free() to free the AlpMblUsatRefreshFileList structure given in the EFs change callback.

Dependencies

The USIM service relies on the Telephony library for access to the phone module.

USAT API ^TOP^

To support a multiple USIM environment, the USAT prototype functions contain an USIM identifier argument.

In the case of a single USIM application, which is the general case, use the default usimId returned by the USIM API:

alp_mbl_usim_get_default_usim_id (AlpMblUsimId* 
oDefaultUsimIdP) 

To send a message to the card (notification, answer, or information):

alp_status_t    alp_mbl_usat_send_to_card		(AlpMblUsimId 
iUsimId, AlpMblUsatMessageId iMessageId, void* iParamP); 

iMessageId is used to define the type of message and should be equal to one of the following values:

• ALP_MBL_USAT_RESPONSE_MESSAGE (1): to send the command result.

  iParamP (through the AlpMblUsatCmdResponse structure) is used to pass the command identifier, a general result, and occasionally more specific information, such as the item identifier.

• ALP_MBL_USAT_EVENT_NOTIFICATION_MESSAGE (2): to notify the card that an event, which is part of the current event list, has occurred.

  iParamP (through the AlpMblUsatEventToCard structure) is used to transfer details of the event to the UICC, including the event code, browser termination cause, and language selection.

• ALP_MBL_USAT_USER_CONFIRMATION_ANSWER_MESSAGE (3): to inform the UICC indirectly that the user accepts or does not accept a request to set up a call, as prompted by the proactive command SETUP CALL.

  iParamP (through the AlpMblCallAction structure) is used to pass the user choice to accept or reject the request.

• ALP_MBL_USAT_MENU_SELECTION_MESSAGE (4): to inform the UICC about the selected menu item.

  iParamP (through the AlpMblUsatMenuSelection structure) is used to pass the identifier of the selected menu item, and eventually, a help request.

To request information:

alp_status_t   alp_mbl_usat_get_setup_menu		(AlpMblUsimId
iUsimId); 

A set of possible menu options is supplied by the card using the proactive command SETUP MENU. This command is directly handled by the mobile daemon as it is not obvious that a Sim Tool Kit application (typically the CAT browser) is already launched when the UICC sends this command.

Therefore, the application uses this API to retrieve the menu items defined by a SETUP MENU command, which was issued previously by the UICC.

Notifications

An STK application registers with Mobile Services to get notifications of proactive command to be executed, to get the envelope command result, and to get notifications of proactive session termination.

For a proactive command notification, the application shall supply and implement a callback function according to the following typedef prototype:

typedef void (*AlpMblUsatWaitingProactiveCommandCallbackPtr)
(AlpMblUsatProactiveCmd* oProactiveCmd);    

All the parameters needed to execute the proactive command are immediately available in the AlpMblUsatProactiveCmd structure. Note that an icon path is indicated when an icon is provided by the UICC.

For a session termination notification, the application shall supply and implement a callback function according to the following typedef prototype

typedef void (*AlpMblUsatEndOfProactiveSessionCallbackPtr)
(void);    

For an envelope command result notification, the application shall supply and implement a callback function according to the following typedef prototype:

typedef void (*AlpMblUsatEnvelopeCommandResultCallbackPtr)
(AlpMblUsatMessageId iMessageId, alp_status_t result);      

After an envelope command, the returned result code ALP_STATUS_OK does not mean that the command is successfully completed. This result code means that the command has been properly sent to the telephony server. When the command is really completed, a result code is returned asynchronously by the telephony server to the mobile server. If this result code is an error, then the mobile server broadcasts a command result notification to the application.

Memory Management

Applications must use alp_mbl_free() to free the AlpMblUsatProactiveCmd structure given in the notification callback when the proactive command is fully handled.

Dependencies

The USAT service depends upon the telephony library for access to the phone module, and the textMgr library for text conversion purposes.