Porting Guide/Telephony

From Tizen Wiki
Jump to: navigation, search


Introduction

Purpose of this document

This document is intended to provide a complete understanding of Tizen Telephony. It covers detailed Telephony Architecture including the various components of Telephony and workflow through Telephony framework. The document also provides Porting guidelines for vendors to ease development of OAL interface for their hardware.

Tizen Telephony features

  • Plug-in Architecture
  • Apache License version 2.0
  • Rich Telecommunication functionalities
  • CMUX support
  • Device ready


Definitions

  • Core Object

Bundle of functions and supportive database information designated to specific Module like; CALL, SS, SIM, Network, etc. which processing Requests/Responses/Notifications. Core Objects form the executable component of a Telephony Module (CALL, SS, SIM, Network, etc.).

  • Template Core Object

Bundle of functions designated to specific Module like; CALL, SS, SIM, Network, etc. which provide the interfaces to process Requests/Responses/Notifications based on the AP-CP interface mechanisms; for example AT-Commands based. Template Core Objects are non-executable components. Executable Core Objects are formed on cloning Template Core Objects.

  • HAL

HAL in other words Hardware Abstraction Layer, abstracts the actual Hardware used and ensures that similar functionality is provided by various hardware (modems) of the same modem vendor. All hardware specific changes are controlled and processed by HALs.

  • Hooks

Hooks provide a mechanism to tap Requests/Responses/Notifications of other Telephony Modules. Hooking is a transparent mechanism and doesn’t affect the normal processing of Requests/Responses/Notifications.



Tizen Telephony Architecture

Tizen Telephony supports plug-in Architecture which provides flexibility to include various types of predefined plug-ins into the system with very less changes.
01.png
Figure 1 provides Tizen Telephony Plug-in Architectural overview. Function calls across various plug-ins are through Tizen Telephony library (libtcore) APIs.

Telephony components

There 3 major components of Tizen Telephony:

Telephony libraries

Telephony provides 2 libraries

i. Telephony API (TAPI) library
- TAPI library (or simply TAPI) is a standardized interface provided to applications to interact with Tizen Telephony.
- It is provided as libtapi package.
- TAPI executes in application’s context, it provides Sync and Async APIs.
Telephony02.png


libtapi internal composition is depicted in Figure 2. Applications can interface to Telephony features like Call, SMS, Network, etc. through the respective module APIs exposed in libtapi.


ii. Core Telephony library (or libtcore)
Telephony03.png


Figure 3 provides the internal composition overview of libtcore.

- Core Telephony library (or libtcore) provides an API framework for Tizen Telephony to inter-work.
- It is provided as libtcore package.
- libtcore provides APIs for
o Creation/destruction/maintenance of various Server components like: Server, Communicator, HAL, Plug-in, Core Object, etc.
o Storage maintenance, Queue mechanism and general utility.
o CMUX support (creation/destruction/processing)
o AT parser

Telephony Plug-ins

There are 4 kinds of Plug-ins –

i. Communicator plug-ins
- Interfaces TAPI and Telephony Server.
- For example, DBUS communicator (DBUS_TAPI); it is provided by ‘default’.
Telephony04.png
ii. Modem plug-ins
- Core functional units providing Telephony functionality.
- Maintain and manage Telephony states.
- Maintain and manage Database related to Telephony.
Telephony05.png
iii. Modem Interface plug-ins
Telephony06.png
- Interfaces Telephony Server to Communication Processor.
- Hardware specific plug-ins which define hardware capabilities and usage.
- Modem Interface plug-in is also called as Hardware Abstraction layer (HAL).
iv. Free Style plug-ins
- Provide completely independent functionality irrespective of hardware (Communication processor).
- For example, plug-ins like packetservice, storage, indicator, etc.
Telephony07.png


Figure 8 provides an overview of all the Telephony Plug-ins together.

Telephony08.png

Telephony Server

- Tizen Telephony runs as a daemon also called as Telephony Server, the daemon is named as telephony-daemon.
- Telephony Server executes as g-main loop from glib library.

Telephony09.png



Porting OAL Interface

OEM vendors can port each and every available plug-in within Telephony as per their needs. It is not mandatory that all the plug-ins to be ported to support a specific hardware. This section provides guidance to OEM vendors to develop various Telephony plug-ins.

Implementation of a Plug-in

Any telephony plug-in is mandatorily required to provide a descriptor structure described below. Table 1: Plug-in descriptor

Structure Description(0-success, -1 - failure)
struct tcore_plugin_define_desc {
gchar *name;
enum tcore_plugin_priority priority;
int version;
gboolean (*load)();
gboolean (*init)(TcorePlugin *);
void (*unload)(TcorePlugin *);
};
Structure referred by Telephony Server to load, initialize, and unload the Plug-in.

This structure defines:

  1. Name of the Plug-in
  2. Initializing priority of the Plug-in
  3. Plug-in version
  4. Plug-in ‘load‘ function reference
  5. Plug-in ‘init‘ function reference
  6. Plug-in ‘unload‘ function reference

Descriptor structure of each plug-in should be named as ‘plugin_define_desc’. Server obtains the address of this symbol in order to provide control to the plug-in to execute its defined functionality.

Order of initialization of a plug-in among various other Telephony plug-ins is defined based on the plug-in’s ‘priority’.

OEMs need to specifically implement Modem and Modem Interface plug-in to support their hardwares. Sample implementations of Modem and Modem Interface plug-ins is available in Appendix section.




Configuration

There are no specific configurations required for Telephony except for conforming to the installation paths of various Telephony plug-ins as mentioned below.

All Telephony plug-ins need to be installed in the following folders –

  1. Modem Plug-ins – /usr/lib/telephony/plugins/modems/
  2. Other Plug-ins – /usr/lib/telephony/plugins/



Appendix

Sample implementation of Modem Interface plug-in

/* Structures for Power on and Rx mechanism */
struct custom_data {
 	int fd;
 	guint watch_id;
 	gboolean on;
};
 									 
static gboolean on_init(TcorePlugin *plugin)
{
 	TcoreHal *hal;
 	struct custom_data *data;
 	dbg("Init!!!");
 									 
 	/* Custom data for Modem Interface Plug-in */
 	dbg("Created custom data memory");
 									 
 	/* Create Physical HAL */
 	dbg("HAL [0x%x] created", hal);
 									 
 	/* Set HAL as Modem Interface Plug-in's User data */
 	tcore_plugin_link_user_data(plugin, hal);
 									 
 	/* Link Custom data to HAL's 'user_data' */
 	tcore_hal_link_user_data(hal, data);
 									 
 	/* Add callbacks for Send/Receive Hooks */
 	tcore_hal_add_send_hook(hal, _on_hal_send, NULL);
 	tcore_hal_add_recv_callback(hal, _on_hal_recv, NULL);
 	dbg("Added Send hook and Receive callback");
 									 
 	/* Set HAL state to Power OFF (FALSE) */
 	tcore_hal_set_power_state(hal, FALSE);
 	dbg("HAL Power State: Power OFF");
 									 
 	/* Resgister to Server */
 	tcore_server_register_modem(tcore_plugin_ref_server(plugin), plugin);
 									 
 	/* Check CP Power ON */
 	g_timeout_add_full(G_PRIORITY_HIGH,
 			 IMC_CP_POWER_ON_TIMEOUT, _power_on, hal, 0);
 	return TRUE;
}
 									 
static enum tcore_hook_return _on_hal_send(TcoreHal *hal,
 		unsigned int data_len, void *data, void *user_data)
{
 	msg("\n====== TX data DUMP ======\n");
 									 
 	return TCORE_HOOK_RETURN_CONTINUE;
}
 									 
static void _on_hal_recv(TcoreHal *hal,
 		unsigned int data_len, const void *data, void *user_data)
{
 	msg("\n====== RX data DUMP ======\n");
}
 									 
static gboolean _power_on(gpointer data)
{
 	struct custom_data *user_data;
 	TcoreHal *hal;
 	gboolean ret;
 	dbg("Entry");
 									 
 	/* Create and Open interface to CP */
 									 
 	/*
 	 *  If Creation or opening of interface to CP fails
 	 * Re-try for pre-defined maximum counts
 	 */
 									 
 	/* If maximum re-try counts expires notify Server */
 	tcore_server_send_notification(server, NULL,
 				TNOTI_SERVER_MODEM_ERR,
 				0, NULL);
 									 
 	/* Free HAL */
 	tcore_hal_free(hal);
 									 
 	return FALSE;
 									 
 	/*
 	 *  If Creation or opening of interface to CP is Successful
 	 *     1. Set HAL Power State
 	 *     2. Check for CP Power state and optional negotiate CMUX
 	 */
 	dbg("Created AP-CP interface");
 									 
 	/* Set HAL Power State ON (TRUE) */
 	tcore_hal_set_power_state(hal, TRUE);
 	dbg("HAL Power State: Power ON");
 									 
 	/* CP is ONLINE, send AT+CPAS */
}
 									 
static void on_unload(TcorePlugin *plugin)
{
 	TcoreHal *hal;
 	struct custom_data *user_data;
 	dbg("Unload!!!");
 									 
 	/* Unload Modem Plug-in */
 	tcore_server_unload_modem_plugin(tcore_plugin_ref_server(plugin), plugin);
 									 
 	/* Unregister Modem Interface Plug-in from Server */
 	tcore_server_unregister_modem(tcore_plugin_ref_server(plugin), plugin);
 	dbg("Unregistered from Server");
 									 
 	/* HAL cleanup */
 									 
 	/* Close CMUX and CMUX channels */
 	tcore_cmux_close(hal, _on_cmux_channel_close, NULL);
 	dbg("CMUX is closed");
 									 
 	/* Free HAL */
 	tcore_hal_free(hal);
 	dbg("Freed HAL");
 									 
 	/* Deinitialize the Physical Channel */
 	dbg("Deinitialized the Channel");
 									 
 	/* Free custom data */
 									 
 	dbg("Unloaded MODEM Interface Plug-in");
}
 									 
/* HAL Operations */
static struct tcore_hal_operations hal_ops = {
 	.power = NULL,
 	.send = _hal_send,
 	.setup_netif = _hal_setup_netif,
};
 									 
static TReturn _hal_send(TcoreHal *hal, unsigned int data_len, void *data)
{
 	/* Get HAL power state, if Powered ON 'write' data */
 									 
 	/* Write data to Device */
 									 
 	return TCORE_RETURN_SUCCESS;;
}
 									 
static TReturn _hal_setup_netif(CoreObject *co,
 			TcoreHalSetupNetifCallback func,
 			void *user_data, unsigned int cid,
 			gboolean enable)
{									 
 	if (enable == TRUE) {    /* Enable device */
 		dbg("ACTIVATE");
 									 
 		/* Open device to send IOCTL command */
 									 
 		/*
 		 * Send IOCTL to change the Channel to Data mode
 		 */
 									 
 		/* Update Device name */
 									 
 		/* Invoke callback function */
 		if (func)
 			func(co, ret, ifname, user_data);
 									 
 		return TCORE_RETURN_SUCCESS;
 	} else {    /* Disable device */
 		dbg("DEACTIVATE");
 		return TCORE_RETURN_SUCCESS;
 	}
}

Sample implementation of Modem plug-in

/* Initializer Table */
struct object_initializer init_table = {
 	.modem_init = s_modem_init,
 	.sim_init = s_sim_init,
 	.sat_init = s_sat_init,
 	.sap_init = s_sap_init,
 	.network_init = s_network_init,
 	.ps_init = s_ps_init,
 	.call_init = s_call_init,
 	.ss_init = s_ss_init,
 	.sms_init = s_sms_init,
 	.phonebook_init = s_phonebook_init,
 	.gps_init = s_gps_init,
};
 									 
/* Deinitializer Table */
struct object_deinitializer deinit_table = {
 	.modem_deinit = s_modem_exit,
 	.sim_deinit = s_sim_exit,
 	.sat_deinit = s_sat_exit,
 	.sap_deinit = s_sap_exit,
 	.network_deinit = s_network_exit,
 	.ps_deinit = s_ps_exit,
 	.call_deinit = s_call_exit,
 	.ss_deinit = s_ss_exit,
 	.sms_deinit = s_sms_exit,
 	.phonebook_deinit = s_phonebook_exit,
 	.gps_deinit = s_gps_exit,
};
 									 
static gboolean on_init(TcorePlugin *p)
{
 	dbg("Init!!!");
 									 
 	/* Initialize Modules (Core Objects) */
 	tcore_object_init_objects(p, &init_table);
 									 
 	/* Subscribe for the Events from CP */
 									 
 	dbg("Init - Successful");
 	return TRUE;
}
 									 
static void on_unload(TcorePlugin *p)
{
 	dbg("Unload!!!");
 									 
 	/* Deinitialize Modules (Core Objects) */
 	tcore_object_deinit_objects(p, &deinit_table);
}

List of libtcore APIs


at

void tcore_at_process_binary_data(TcoreAT *at,char *position,int data_len);
 									 
gboolean tcore_at_add_hook(TcoreHal *hal, void *hook_func);
TcoreAT *tcore_at_new(TcoreHal *hal);
void tcore_at_free(TcoreAT *at);
 									 
TReturn tcore_at_buf_write(TcoreAT *at, unsigned int data_len, const char *data);
 									 
TReturn tcore_at_set_request(TcoreAT *at, TcoreATRequest *req, gboolean send);
TcoreATRequest *tcore_at_get_request(TcoreAT *at);
TcoreATResponse *tcore_at_get_response(TcoreAT *at);
 									 
TReturn tcore_at_add_notification(TcoreAT *at, const char *prefix,
 			gboolean pdu, TcoreATNotificationCallback callback,
 			void *user_data);
TReturn tcore_at_remove_notification(TcoreAT *at, const char *prefix,
 			TcoreATNotificationCallback callback);
TReturn tcore_at_remove_notification_full(TcoreAT *at,
 			const char *prefix,
 			TcoreATNotificationCallback callback, void *user_data);
 									 
TcoreATRequest *tcore_at_request_new(const char *cmd, const char *prefix,
 			enum tcore_at_command_type type);
void tcore_at_request_free(TcoreATRequest *req);
 									 
gboolean tcore_at_process(TcoreAT *at, unsigned int data_len, const char *data);
 									 
TcorePending *tcore_at_pending_new(CoreObject *co, const char *cmd,
 			const char *prefix, enum tcore_at_command_type type,
 			TcorePendingResponseCallback func, void *user_data);
 									 
GSList *tcore_at_tok_new(const char *line);
void tcore_at_tok_free(GSList *tokens);
char *tcore_at_tok_extract(const char *src);
char *tcore_at_tok_nth(GSList *tokens, unsigned int token_index);
 									 
TReturn tcore_prepare_and_send_at_request(CoreObject *co,
 			const char *at_cmd,
 			const char *at_cmd_prefix,
 			enum tcore_at_command_type at_cmd_type,
 			UserRequest *ur,
 			TcorePendingResponseCallback resp_cb,
 			void *resp_cb_data,
 			TcorePendingSendCallback send_cb,
 			void *send_cb_data);

communicator

Communicator *tcore_communicator_new(TcorePlugin *plugin, const char *name,
 			struct tcore_communitor_operations *ops);
void tcore_communicator_free();
 									 
TcorePlugin *tcore_communicator_ref_plugin(Communicator *comm);
const char *tcore_communicator_ref_name(Communicator *comm);
 									 
TReturn tcore_communicator_link_user_data(Communicator *comm, void *data);
void *tcore_communicator_ref_user_data(Communicator *comm);
 									 
TReturn tcore_communicator_send_response(Communicator *comm,
 			UserRequest *ur,  enum tcore_response_command command,
 			unsigned int data_len, const void *data);
 									 
TReturn tcore_communicator_send_notification(Communicator *comm,
 			CoreObject *source, enum tcore_notification_command command,
 			unsigned int data_len, const void *data);
 									 
TReturn tcore_communicator_dispatch_request(Communicator *comm, UserRequest *ur);

core_object

CoreObject *tcore_object_new(TcorePlugin *plugin, TcoreHal *hal);
void tcore_object_free(CoreObject *co);
 									 
TReturn tcore_object_set_free_hook(CoreObject *co, tcore_object_free_hook free_hook);
TReturn tcore_object_set_clone_hook(CoreObject *co, tcore_object_clone_hook clone_hook);
 									 
CoreObject *tcore_object_clone(CoreObject *src, TcorePlugin *new_parent);
CoreObject *tcore_object_clone_template_object(TcorePlugin *p, unsigned int co_type);
 									 
 									 
TReturn tcore_object_set_plugin(CoreObject *co, TcorePlugin *plugin);
TcorePlugin *tcore_object_ref_plugin(CoreObject *co);
 									 
TReturn tcore_object_link_object(CoreObject *co, void *object);
void *tcore_object_ref_object(CoreObject *co);
 									 
TReturn tcore_object_set_type(CoreObject *co, unsigned int type);
unsigned int tcore_object_get_type(CoreObject *co);
 									 
TReturn tcore_object_set_hal(CoreObject *co, TcoreHal *hal);
TcoreHal *tcore_object_get_hal(CoreObject *co);
 									 
TReturn tcore_object_link_user_data(CoreObject *co, void *user_data);
void *tcore_object_ref_user_data(CoreObject *co);
 									 
TReturn tcore_object_set_dispatcher(CoreObject *co, tcore_object_dispatcher func);
TReturn tcore_object_dispatch_request(CoreObject *co, UserRequest *ur);
 									 
TReturn tcore_object_add_callback(CoreObject *co, const char *event,
 			 tcore_object_callback callback, void *user_data);
TReturn tcore_object_del_callback(CoreObject *co, const char *event, tcore_object_callback callback);
TReturn tcore_object_override_callback(CoreObject *co, const char *event, tcore_object_callback callback, void *user_data);
TReturn tcore_object_emit_callback(CoreObject *co, const char *event, const void *event_info);
 									 
void *tcore_object_add_mapping_tbl_entry(void *mapping_tbl, unsigned int object_type, TcoreHal *hal);
 									 
void tcore_object_remove_mapping_tbl(void *mapping_tbl);
void *tcore_object_remove_mapping_tbl_entry(void *mapping_tbl, TcoreHal *hal);
void tcore_object_remove_mapping_tbl_entry_by_type(void *mapping_tbl, unsigned int co_type);
 									 
 									 
void tcore_object_print_mapping_tbl(void *mapping_tbl);
 									 
TReturn tcore_object_init_objects(TcorePlugin *plugin, struct object_initializer *initializer_list);
 									 
void tcore_object_deinit_objects(TcorePlugin *plugin, struct object_deinitializer *deinitializer_list);

hal

TcoreHal *tcore_hal_new(TcorePlugin *plugin, const char *name,
 			struct tcore_hal_operations *hops,
 			enum tcore_hal_mode mode);
void tcore_hal_free(TcoreHal *hal);
 									 
TReturn tcore_hal_set_name(TcoreHal *hal, const char *name);
char *tcore_hal_get_name(TcoreHal *hal);
 									 
TcoreAT *tcore_hal_get_at(TcoreHal *hal);
enum tcore_hal_mode tcore_hal_get_mode(TcoreHal *hal);
TReturn tcore_hal_set_mode(TcoreHal *hal, enum tcore_hal_mode mode);
 									 
TReturn tcore_hal_set_power(TcoreHal *hal, gboolean flag);
 									 
TReturn tcore_hal_link_user_data(TcoreHal *hal, void *user_data);
void *tcore_hal_ref_user_data(TcoreHal *hal);
 									 
TReturn tcore_hal_send_data(TcoreHal *hal, unsigned int data_len, void *data);
TReturn tcore_hal_send_request(TcoreHal *hal, TcorePending *pending);
TReturn tcore_hal_send_force(TcoreHal *hal);
 									 
TReturn tcore_hal_dispatch_response_data(TcoreHal *hal, int id,
 			unsigned int data_len, const void *data);
 									 
TReturn tcore_hal_add_recv_callback(TcoreHal *hal, TcoreHalReceiveCallback func, void *user_data);
TReturn tcore_hal_remove_recv_callback(TcoreHal *hal, TcoreHalReceiveCallback func);
TReturn tcore_hal_emit_recv_callback(TcoreHal *hal, unsigned int data_len, const void *data);
TReturn tcore_hal_add_send_hook(TcoreHal *hal, TcoreHalSendHook func, void *user_data);
TReturn tcore_hal_remove_send_hook(TcoreHal *hal, TcoreHalSendHook func);
 									 
TReturn tcore_hal_set_power_state(TcoreHal *hal, gboolean flag);
gboolean tcore_hal_get_power_state(TcoreHal *hal);
 									 
TcoreQueue *tcore_hal_ref_queue(TcoreHal *hal);
TcorePlugin *tcore_hal_ref_plugin(TcoreHal *hal);
 									 
TReturn tcore_hal_setup_netif(TcoreHal *hal, CoreObject *co,
 			TcoreHalSetupNetifCallback func,
 			void *user_data, unsigned int cid,
 			gboolean enable);

mux

TReturn tcore_cmux_init(TcoreHal *phy_hal, unsigned int frame_size,
 			TcorePendingResponseCallback resp_cb, void *resp_cb_data);
 									 
TReturn tcore_cmux_setup_internal_mux(tcore_cmux_mode mode,
 	int max_channels, unsigned int cmux_buf_size, TcoreHal *phy_hal,
 	cmux_setup_cb_func channel_setup_cb, gpointer channel_setup_user_data,
 	cmux_setup_complete_cb_func setup_complete_cb, gpointer setup_complete_user_data);
 									 
void tcore_cmux_close(TcoreHal *phy_hal,
 	cmux_channel_close_cb_func channel_close_cb, gpointer channel_close_user_data);
 									 
void tcore_cmux_rcv_from_hal(TcoreHal *hal, unsigned char *data, size_t length);

plugin

TcorePlugin *tcore_plugin_new(Server *server,
 			const struct tcore_plugin_define_desc *desc,
 			const char *filename, void *handle);
void tcore_plugin_free(TcorePlugin *plugin);
 									 
const struct tcore_plugin_define_desc *tcore_plugin_get_description(TcorePlugin *plugin);
 									 
char *tcore_plugin_get_filename(TcorePlugin *plugin);
char *tcore_plugin_ref_plugin_name(TcorePlugin *plugin);
Server *tcore_plugin_ref_server(TcorePlugin *plugin);
 									 
TReturn tcore_plugin_link_user_data(TcorePlugin *plugin, void *user_data);
void *tcore_plugin_ref_user_data(TcorePlugin *plugin);
 									 
TReturn tcore_plugin_add_core_object(TcorePlugin *plugin, CoreObject *co);
CoreObject *tcore_plugin_ref_core_object(TcorePlugin *plugin, unsigned int type);
GSList *tcore_plugin_get_core_objects_bytype(TcorePlugin *plugin, unsigned int type);
 									 
TReturn tcore_plugin_core_object_event_emit(TcorePlugin *plugin, 
 			const char *event, const void *event_info);
 									 
TReturn tcore_plugin_link_property(TcorePlugin *plugin, const char *key, void *data);
void *tcore_plugin_ref_property(TcorePlugin *plugin, const char *key);

queue

TcorePending *tcore_pending_new(CoreObject *co, unsigned int id);
void tcore_pending_free(TcorePending *pending);
 									 
unsigned int tcore_pending_get_id(TcorePending *pending);
TReturn tcore_pending_set_auto_free_status_after_sent(TcorePending *pending, gboolean flag);
gboolean tcore_pending_get_auto_free_status_after_sent(TcorePending *pending);
TReturn tcore_pending_set_request_data(TcorePending *pending, unsigned int data_len, void *data);
void *tcore_pending_ref_request_data(TcorePending *pending, unsigned int *data_len);
TReturn tcore_pending_set_timeout(TcorePending *pending, unsigned int timeout);
TcorePlugin *tcore_pending_ref_plugin(TcorePending *pending);
CoreObject *tcore_pending_ref_core_object(TcorePending *pending);
TReturn tcore_pending_set_priority(TcorePending *pending,
 			enum tcore_pending_priority priority);
TReturn tcore_pending_get_priority(TcorePending *pending,
 			enum tcore_pending_priority *result_priority);
TReturn tcore_pending_get_send_status(TcorePending *pending, gboolean *result_status);
TReturn tcore_pending_link_user_request(TcorePending *pending, UserRequest *ur);
UserRequest *tcore_pending_ref_user_request(TcorePending *pending);
 									 
TReturn tcore_pending_set_send_callback(TcorePending *pending,
 			TcorePendingSendCallback func, void *user_data);
TReturn tcore_pending_emit_send_callback(TcorePending *pending, int bytes);
 									 
TReturn tcore_pending_set_timeout_callback(TcorePending *pending,
 			TcorePendingTimeoutCallback func, void *user_data);
TReturn tcore_pending_emit_timeout_callback(TcorePending *pending);
 									 
TReturn tcore_pending_set_response_callback(TcorePending *pending,
 			TcorePendingResponseCallback func, void *user_data);
TReturn tcore_pending_emit_response_callback(TcorePending *pending,
 			int data_len, const void *data);
 									 
TcoreQueue *tcore_queue_new(TcoreHal *hal);
void tcore_queue_free(TcoreQueue *qeueu);
 									 
TReturn tcore_queue_push(TcoreQueue *queue, TcorePending *pending);
TcorePending *tcore_queue_pop(TcoreQueue *queue);
TcorePending *tcore_queue_pop_by_pending(TcoreQueue *queue, TcorePending *pending);
TcorePending *tcore_queue_pop_timeout_pending(TcoreQueue *queue);
TcorePending *tcore_queue_ref_head(TcoreQueue *queue);
TcorePending *tcore_queue_ref_tail(TcoreQueue *queue);
TcorePending *tcore_queue_pop_by_id(TcoreQueue *queue, unsigned int id);
TcorePending *tcore_queue_ref_pending_by_id(TcoreQueue *queue, unsigned int id);
TcorePending *tcore_queue_ref_next_pending(TcoreQueue *queue);
unsigned int tcore_queue_get_length(TcoreQueue *queue);
TcoreHal *tcore_queue_ref_hal(TcoreQueue *queue);
TReturn tcore_queue_cancel_pending_by_command(TcoreQueue *queue,
 			enum tcore_request_command command);
TcorePending *tcore_queue_search_by_command(TcoreQueue *queue,
 			enum tcore_request_command command, gboolean flag_sent);

server

Server *tcore_server_new();
void tcore_server_free(Server *s);
 									 
TReturn tcore_server_run(Server *s);
TReturn tcore_server_exit(Server *s);
 									 
TReturn tcore_server_add_plugin(Server *s, TcorePlugin *plugin);
GSList *tcore_server_ref_plugins(Server *s);
TcorePlugin *tcore_server_find_plugin(Server *s, const char *name);
 									 
TReturn tcore_server_add_communicator(Server *s, Communicator *comm);
GSList *tcore_server_ref_communicators(Server *s);
Communicator *tcore_server_find_communicator(Server *s, const char *name);
 									 
TReturn tcore_server_add_storage(Server *s, Storage *strg);
GSList *tcore_server_ref_storages(Server *s);
Storage * tcore_server_find_storage(Server *s, const char *name);
 									 
TReturn tcore_server_add_template_object(Server *s, CoreObject *template_co);
GSList *tcore_server_ref_template_object(Server *s);
CoreObject *tcore_server_find_template_object(Server *s, unsigned int type);
 									 
TReturn tcore_server_link_udev(Server *s, TcoreUdev *udev);
TcoreUdev *tcore_server_ref_udev(Server *s);
 									 
TReturn tcore_server_dispatch_request(Server *s, UserRequest *ur);
TReturn tcore_server_send_notification(Server *s, CoreObject *source,
 			enum tcore_notification_command command,
 			unsigned int data_len, void *data);
 									 
TReturn tcore_server_add_request_hook(Server *s,
 			enum tcore_request_command command,
 			tcore_server_request_hook func, void *user_data);
TReturn tcore_server_remove_request_hook(Server *s,
 			tcore_server_request_hook func);
TReturn tcore_server_add_notification_hook(Server *s,
 			enum tcore_notification_command command,
 			tcore_server_notification_hook func, void *user_data);
TReturn tcore_server_remove_notification_hook(Server *s,
 			tcore_server_notification_hook func);
 									 
gboolean tcore_server_register_modem(Server *s, TcorePlugin *modem_iface_plugin);
void tcore_server_unregister_modem(Server *s, TcorePlugin *modem_iface_plugin);
gboolean tcore_server_update_modem_plugin(TcorePlugin *modem_iface_plugin,
 			TcorePlugin *modem_plugin);
GSList *tcore_server_get_cp_name_list(Server *s);
const char *tcore_server_get_cp_name_by_plugin(TcorePlugin *plugin);
 									 
gboolean tcore_server_add_cp_mapping_tbl_entry(TcorePlugin *modem_iface_plugin,
 			unsigned int co_type, TcoreHal *hal);
void tcore_server_remove_cp_mapping_tbl(TcorePlugin *modem_iface_plugin);
void tcore_server_remove_cp_mapping_tbl_entry(TcorePlugin *modem_iface_plugin, TcoreHal *hal);
void *tcore_server_get_cp_mapping_tbl(TcorePlugin *modem_plugin);
 									 
void tcore_server_print_modems(TcorePlugin *plugin);
 									 
TReturn tcore_server_load_modem_plugin(Server *s, TcorePlugin *modem_if_plugin,
 			const char *name);
void tcore_server_unload_modem_plugin(Server *s, TcorePlugin *modem_if_plugin);

storage

Storage *tcore_storage_new(TcorePlugin *plugin, const char *name, struct storage_operations *ops);
void  tcore_storage_free(Storage *strg);
const char *tcore_storage_ref_name(Storage *strg);
 									 
void *tcore_storage_create_handle(Storage *strg, const char *path);
gboolean tcore_storage_remove_handle(Storage *strg, void *handle);
 									 
gboolean tcore_storage_set_int(Storage *strg, enum tcore_storage_key key, int value);
int tcore_storage_get_int(Storage *strg, enum tcore_storage_key key);
 									 
gboolean tcore_storage_set_string(Storage *strg, enum tcore_storage_key key, const char *value);
char *tcore_storage_get_string(Storage *strg, enum tcore_storage_key key);
 									 
gboolean tcore_storage_set_bool(Storage *strg, enum tcore_storage_key key, gboolean value);
gboolean tcore_storage_get_bool(Storage *strg, enum tcore_storage_key key);
 									 
gboolean tcore_storage_set_key_callback(Storage *strg,
 	enum tcore_storage_key key, TcoreStorageKeyCallback cb, void *user_data);
gboolean     tcore_storage_remove_key_callback(Storage *strg,
 	enum tcore_storage_key key, TcoreStorageKeyCallback cb);
 									 
gboolean tcore_storage_update_query_database(Storage *strg, void *handle,
 	const char *query, GHashTable *in_param);
gboolean tcore_storage_read_query_database(Storage *strg, void *handle,
 	const char *query, GHashTable *in_param, GHashTable *out_param, int out_param_cnt);
gboolean tcore_storage_insert_query_database(Storage *strg, void *handle,
 	const char *query, GHashTable *in_param);
gboolean tcore_storage_remove_query_database(Storage *strg, void *handle,
 	const char *query, GHashTable *in_param);

udev

TcoreUdev *tcore_udev_new(Server *s, const gchar **subsystems);
void tcore_udev_free(TcoreUdev *udev);
 									 
Server *tcore_udev_ref_server(TcoreUdev *udev);
GUdevClient *tcore_udev_ref_client(TcoreUdev *udev);
GUdevEnumerator *tcore_udev_ref_enumerator(TcoreUdev *udev);
 									 
TReturn tcore_udev_add_enumerator_callback(TcoreUdev *udev, TcoreUdevEnumerCallback func,
 				void *user_data);
GList *tcore_udev_exec_enumerator(TcoreUdev *udev, gboolean event_emit_flag);
TReturn tcore_udev_add_callback(TcoreUdev *udev, const char *subsystem,
 				const char *action, TcoreUdevCallback func, void *user_data);
 									 
'''user_request'''
UserRequest *tcore_user_request_new(Communicator *comm, const char *modem_name);
void tcore_user_request_free(UserRequest *ur);
 									 
UserRequest *tcore_user_request_ref(UserRequest *ur);
void tcore_user_request_unref(UserRequest *ur);
 									 
TReturn tcore_user_request_set_free_hook(UserRequest *ur, UserRequestFreeHook free_hook);
TReturn tcore_user_request_set_response_hook(UserRequest *ur,
 			UserRequestResponseHook resp_hook, void *user_data);
 									 
Communicator *tcore_user_request_ref_communicator(UserRequest *ur);
char *tcore_user_request_get_modem_name(UserRequest *ur);
 									 
TReturn tcore_user_request_set_user_info(UserRequest *ur, const struct tcore_user_info *ui);
const struct tcore_user_info * tcore_user_request_ref_user_info(UserRequest *ur);
 									 
TReturn tcore_user_request_send_response(UserRequest *ur,
 			enum tcore_response_command command,
 			unsigned int data_len, const void *data);
 									 
TReturn tcore_user_request_set_command(UserRequest *ur,
 			enum tcore_request_command command);
enum tcore_request_command tcore_user_request_get_command(UserRequest *ur);
 									 
TReturn tcore_user_request_set_data(UserRequest *ur,
 			unsigned int data_len, const void *data);
const void *tcore_user_request_ref_data(UserRequest *ur, unsigned int *data_len);
 									 
TReturn tcore_user_request_set_metainfo(UserRequest *ur,
 			unsigned int metainfo_len, const void *metainfo);
const void *tcore_user_request_ref_metainfo(UserRequest *ur, unsigned int *metainfo_len);

util

TReturn tcore_util_netif(const char *name, gboolean enabled);
TReturn tcore_util_netif_set(const char *name, const char *ipaddr,
 		const char *gateway, const char *netmask);
 									 
char *tcore_util_get_string_by_ip4type(union tcore_ip4_type ip);
 									 
GHashTable *tcore_util_marshal_create();
void tcore_util_marshal_destory(GHashTable *ht);
 									 
GHashTable *tcore_util_marshal_deserialize_string(const gchar *serialized_string);
gchar *tcore_util_marshal_serialize(GHashTable *ht);
 									 
gboolean tcore_util_marshal_add_data(GHashTable *ht, const gchar *key,
 		const void *data, enum tcore_util_marshal_data_type type);
gboolean tcore_util_marshal_get_data(GHashTable *ht, const gchar *key,
 		void **data, enum tcore_util_marshal_data_type type);
 									 
gint tcore_util_marshal_get_int(GHashTable *ht, const gchar *key);
gchar *tcore_util_marshal_get_string(GHashTable *ht, const gchar *key);
GHashTable *tcore_util_marshal_get_object(GHashTable *ht, const gchar *key);
 									 
enum tcore_dcs_type tcore_util_get_cbs_coding_scheme(unsigned char encode);
 									 
unsigned char *tcore_util_decode_hex(const char *src, int len);
long tcore_util_encode_hex(const unsigned char *src, long num_bytes, char *buf);
 									 
int tcore_util_pdu_encode(const unsigned char *sca, const unsigned char *tpdu, int tpdu_len,
 		char *pdu);
unsigned char *tcore_util_unpack_gsm7bit(const unsigned char *src, unsigned int src_len);
unsigned char *tcore_util_pack_gsm7bit(const unsigned char *src, unsigned int src_len);
char *tcore_util_convert_bcd2ascii(const char *src, int src_len, int max_len);
gboolean tcore_util_convert_utf8_to_gsm(unsigned char *dest, int *dest_len,
 		unsigned char* src, int src_len);
gboolean tcore_util_convert_utf8_to_ucs2(unsigned char* dest, int* dest_len,
 		unsigned char* src, int src_len);
gboolean tcore_util_convert_string_to_utf8(unsigned char *dest, unsigned short *dest_len, enum alphabet_format dcs, const unsigned char *src, unsigned short src_len);
		
void tcore_util_swap_byte_order(unsigned short* dest, const unsigned short* src, int src_len);
 									 
char *tcore_util_get_version(void);

Workflow

I. Initialization sequence
Telephony loading sequence (as shown in Figure 10) –
  1. Server loads Modem Interface plug-in
  2. Modem Interface plug-in registers to Server
  3. Server enumerates Modem Interface plug-in
  4. Create Physical HAL
  5. Modem Interface plug-in queries Modem State
  6. If Modem is ONLINE then, CMUX (internal) channels are established
  7. Logical HAL is created for each CMUX channel and assigned for a Core Object type, these are updated to mapping table.
  8. Change Physical HAL mode to TRANSPARENT (disables Queue)
  9. Modem Interface plug-in requests server to load Modem plug-in (corresponding to its Architecture)
  10. Server loads Modem plug-in
  11. Modem plug-in initializes sub-modules and creates Core Objects (based on the Core Object types defined in the mapping table by Modem Interface plug-in)
  12. Modem plug-in notifies Server of the event PLUGIN_ADDED
  13. Modem notifies Communicator of the event PLUGIN_ADDED
  14. Communicator creates interfaces for the Sub-modules present (based on the Core objects created)
Telephony10.png
II. Request processing sequence
Telephony Request processing sequence (as shown in Figure 11) –
  1. Application Request is sent to Communicator through TAPI
  2. Communicator creates User Request based on the incoming Request
  3. User Request is dispatch to Communicator
  4. Communicator dispatches User Request to Server
  5. Server finds the plug-in based on modem name
  6. Server extracts the Core Object type based on the Request command from plug-in’s Core Objects list
  7. Server dispatches User Request to Core Object
  8. Core Object dispatches User Request to dispatch function based on Request command
  9. Pending Request is formed, added to Queue and sent to Logical HAL assigned for the Core Object
  10. Logical HAL dispatches the Request data to a CMUX channel dedicated to it
  11. CMUX encodes the Request data and dispatches to Physical HAL
  12. Physical HAL sends the Request data to Modem
Telephony11.png
III. Response processing sequence
Telephony Response processing sequence (as shown in Figure 12) –
  1. Response data sent by Modem is received by Physical HAL
  2. Physical HAL dispatches the Response data to CMUX
  3. CMUX decodes the received Response data and dispatches the corresponding Logical HAL based on the CMUX channel
  4. Logical HAL dispatches the decoded Response data to the corresponding Core Object
  5. Core Object processes the received Response data and extracts the User Request from pending Queue and sends the Response data corresponding to User Request
  6. User Request extracts the Communicator
  7. Received Response data is sent to the corresponding Communicator
  8. Communicator sends the Response data to TAPI which communicates the Response to application
Telephony12.png
IV. Indication processing sequence
Telephony Indication processing sequence (as shown in Figure 13) –
  1. Notification data sent by Modem is received by Physical HAL
  2. Physical HAL dispatches the Notification data to CMUX
  3. CMUX decodes the received Notification data and dispatches the corresponding Logical HAL based on the CMUX channel registered for the Notification
  4. Logical HAL dispatches the decoded Notification data to the corresponding Core Object that registered for the Notification
  5. Core Object processes the received Notification data and dispatches to Server
  6. Server dispatches the Notification data to corresponding Communicator
  7. Communicator sends the Notification data to TAPI which communicates the same to application
Telephony13.png

Further References

[1] http://review.tizen.org/git/ - Tizen source website
[2] Telephony packages

framework/telephony/libtcore.git – Telephony Core Library
framework/telephony/libtapi.git – TAPI
framework/telephony/tel-plugin-dbus_tapi.git – Communicator (DBUS_TAPI)
framework/telephony/tel-plugin-at_standard.git – AT Standard plug-in
framework/telephony/tel-plugin-indicator.git – Free Style plug-in (Indicator)
framework/telephony/tel-plugin-packetservice.git – Free Style plug-in (packetservice)
framework/telephony/tel-plugin-vconf.git – Free Style plug-in (Database)
framework/telephony/tel-plugin-database.git – Free Style plug-in (VCONF)
framework/telephony/tel-plugin-imc.git – Modem plug-in (device)
framework/telephony/tel-plugin-imcmodem.git – Modem Interface plug-in (device)
framework/telephony/tel-plugin-atmodem.git – Modem plug-in (emulator)
framework/telephony/tel-plugin-vmodem.git – Modem Interface plug-in (emulator)