Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages | Examples

Actions

Detailed Description

Actions are used by kernel to inform application that some situation or event occured and is up to the application to react. Optionally kernel may append some data related to the given action.

app_struct.png

Application structure

Actions could be divided by several criteria:

The basic actions are related to application life cycle - they are invoked when e.g. the application is loaded into memory, when there is time for the application to initialize itself or when the application is unloaded from memory and should clean up resources it used.

app_lifecycle.png

Application lifecycle

Non registerable lifecycle related actions:

Registerable actions but not by reg_action():

Registerable actions registered by reg_action():

These actions should be registered always during initalization (ACTION_APP_INIT) or on demand and can be unregistered by unreg_action(). If *_EVENT_* action is set up ad hoc you have to call the set_up_event_list() call to inform ME to update the event list.

Data Structures

Defines

Typedefs

Functions

Define Documentation

#define ACTION_APP_INIT
 

Invoked for application to initialize its internals.

See also:
_init()

#define ACTION_APP_REGISTER
 

Invoked for application registration.

Called only once when the application is loaded into the memory. By registration we mean one time process, when application can e.g. allocate EEPROM structures, reg_sms_tag(), reg_file_type() etc.

#define ACTION_APP_UNREGISTER
 

Invoked when application is unloaded from memory.

Application should clear the resources it used (EEPROM).

#define ACTION_BCCH_UPDATE
 

Invoked when ME updates EF_BCCH

#define ACTION_CALL_CONTROL
 

ENVELOPE CALL CONTROL, Ref. 11.14

#define ACTION_EVENT_BROWSER_TERMINATION
 

ENVELOPE Browser Termination Event, Ref. 11.14

#define ACTION_EVENT_CALL_CONNECTED
 

ENVELOPE Call Connected Event, Ref. 11.14

#define ACTION_EVENT_CALL_DISCONNECTED
 

ENVELOPE Call Disconnected Event, Ref. 11.14

#define ACTION_EVENT_CARD_READER_STATUS
 

ENVELOPE Card Reader Status Event, Ref. 11.14

#define ACTION_EVENT_CHANNEL_STATUS
 

ENVELOPE Channel Status Event, Ref. 11.14

#define ACTION_EVENT_DATA_AVAILABLE
 

ENVELOPE Data Available Event, Ref. 11.14

#define ACTION_EVENT_IDLE_SCREEN
 

ENVELOPE Idle Screen Available Event, Ref. 11.14

#define ACTION_EVENT_LANGUAGE_SELECTION
 

ENVELOPE Language Selection Event, Ref. 11.14

#define ACTION_EVENT_LOCATION_STATUS
 

ENVELOPE Location Status Event, Ref. 11.14

#define ACTION_EVENT_MT_CALL
 

ENVELOPE MT Call Event, Ref. 11.14

#define ACTION_EVENT_USER_ACTIVITY
 

ENVELOPE User Activity Event, Ref. 11.14

#define ACTION_FILE_APDU
 

Invoked when ME requests file registered by the reg_file() call.

u8 PROGMEM fake_file_path[]= { 0x3F, 0x00, 0x7F, 0x20, 0x6F, 0x07 };

void handle_fake_file(File_apdu_data *fa)
{
}

void turbo_handler(u8 action, void * data)
{
switch(action)
{
...
        case    ACTION_APP_INIT:
                reg_file(fake_file_path,3);
                break;
        case    ACTION_FILE_APDU:
                handle_fake_file(data);
                break;
...
}

#define ACTION_FIRST_STK
 

Invoked upon start up when ME is ready to handle STK commands, after menu is set.

#define ACTION_IDLE_TASK
 

Register this action if you want turbo (your application) to operate also between APDUs.

Following should be considered when using idle task:

  1. registration has to happen during early during SIM initialization. This is because we have to inform ME not to stop clocks.
  2. It may not be possible to reregister ACTION_IDLE_TASK because some phones ask about clock stopping only once.
  3. Idle operation consumes more power - turbo does not sleep and clocks are on.
  4. Clock frequency can be lower than during normal operation (1/3).

#define ACTION_INSERT_MENU
 

Request for application to insert its menu items. Application may insert more than one item by insert_menu(). This action is invoked whenever either SIM or turbo wants to set up new menu list. It can happen ad hoc, e.g. user loads new application or changes language, etc.

#define ACTION_LOCI_UPDATE
 

Invoked when ME updates EF_LOCI

#define ACTION_MENU_SELECTION
 

Invoked when menu item was selected by the user.

The application can have more than one item in top level menu inserted (max. 4). Example: 

lc_char PROGMEM lc_Item_A[]={
        LC_EN("Item A")
        LC_END
};

lc_char PROGMEM lc_Item_B[]={
        LC_EN("Item B")
        LC_END
};

void action_menu(Menu_selection_data * x)
{
if(x->item==0)
 {
        // Item A
 }
else  //x==1
 {
        // Item B 
 }
}

void turbo_handler(u8 action, void * data)
{
 switch(action)
  {
   ...
        case    ACTION_INSERT_MENU:
                insert_menu(locale(lc_Item_A));
                insert_menu(locale(lc_Item_B));
                break;
        case    ACTION_MENU_SELECTION:
                stk_thread(action_menu, data);
                break;
   ...
  }
}

#define ACTION_MO_SMS_CONTROL
 

ENVELOPE MO SMS CONTROL, Ref. 11.14

#define ACTION_RUN_GSM_ALGORITHM
 

Invoked when ME asks SIM APDU RUN GSM ALGORITHM.

#define ACTION_SMS
 

Invoked when SMS is received.

See also:
store_sms_2_sim()

#define ACTION_SMS_A
 

Invoked when answer Turbo SMS of registered SMS_TYPE_QA type is received.

#define ACTION_SMS_CB_DOWNLOAD
 

ENVELOPE CELL BROADCAST DOWNLOAD, Ref. 11.14

#define ACTION_SMS_MSG
 

Invoked when message Turbo SMS of registered SMS_TYPE_MSG type is received.

#define ACTION_SMS_PP_DOWNLOAD
 

ENVELOPE SMS-PP DOWNLOAD, Ref. 11.14

#define ACTION_SMS_Q
 

Invoked when question Turbo SMS of registered SMS_TYPE_QA type is received.

#define ACTION_STATUS
 

Invoked by ME APDU STATUS command. Usually every 30sec in idle.

#define ACTION_TERMINAL_PROFILE
 

Invoked when ME sends GSM_TERMINAL_PROFILE cmd. Since then the return value of terminal_profile() is valid.

#define ACTION_TIMER_EXPIRATION
 

Invoked when ME signals EVENT that timer has expired.

Typedef Documentation

typedef struct _File_apdu_data File_apdu_data
 

Structure passed with ACTION_FILE_APDU action to application.

typedef struct _Menu_selection_data Menu_selection_data
 

Structure passed with ACTION_MENU_SELECTION action to application. inserted with insert_menu() (max. 4 items can be inserted by one application).

typedef void( t_turbo_main)(u8 action, void *data)
 

Turbo handler type definition.

Function Documentation

u8 reg_action (  u8  action  ) 
 

Register action.

Parameters:
action 
Returns:
NO_ERROR or ERR_RESOURCE_BUSY (some actions can be registered by only one appliacation).
See also:
set_up_event_list(), unreg_action()
Examples:
alarm.c, alarm_flipflop.c, cells.c, certs.c, fake_sim.c, net.c, switch.c, and test_idle.c.

u8 stk_thread (  void(*  start_routine)(void *),
void *  arg
) 
 

Spawn new SIM Toolkit thread. The new thread applies the function start_routine passing it arg as first argument.

Parameters:
start_routine 
arg 
Returns:
NO_ERROR, ERR_NO_RAM
Examples:
adc.c, alarm.c, alarm_flipflop.c, braled.c, braping.c, browser.c, calc.c, callback.c, certs.c, fake_sim.c, firststk.c, hello_world.c, hello_world_ucs2.c, mc.c, net.c, pos.c, reader.c, shmem.c, stkcmd.c, sysinfo.c, temperature.c, test_idle.c, test_img.c, test_prot_mem.c, test_refresh.c, timer.c, topmenu.c, and tsmsacl.c.

void unreg_action (  u8  action  ) 
 

Unregister action.

Parameters:
action 
See also:
reg_action()
Examples:
fake_sim.c, and test_idle.c.

u8* wait_for_action (  u8  action,
const u8 *  alpha,
u8  nr_rep
) 
 

Wait for ACTION and display alpha text meanwhile. If alpha text is NULL more_time() is used and no text is displayed.

The number of repeatings says how many times display_text() or more_time() is fetched.

Warning:
SIM Toolkit function, usable only in stk_thread().
Parameters:
action ACTION_EVENT_DATA_AVAILABLE
alpha pointer on ALPHA text, can be from RAM, EEPROM, PROGMEM
nr_rep number of repeats to display alpha
Returns:
ENVELOPE or TERMINAL RESPONSE in buf_A().
Examples:
net.c.

Copyright © 2004-2006 BLADOX
Turbo version 1.2