All call operations are asynchronous and return almost immediately. 5

Libvocenabler

1 Overview

1.1 Introduction

Libvocenabler is a library which provides application developers with high-level technology agnostic APIs to dial, to accept, to hang up and other means to manage voice calls. Different low level telephony services may lie behind the APIs.

1.2 Features:

--Technology agnostic

The APIs will not expose to applications any feature specific to the bearer (e.g. circuit switched or IP telephony) or the protocol (e.g. H323 or SIP) actually used to dial or to receive calls. Different low level telephony services may lie behind the APIs. The Voice Call Enabler implementation will dispatch calls form (to) applications to (from) the corresponding low-level telephony services according to the application requests and the enabler configuration.

--Libvocenabler is released under the LIPS License.

--Libvocenabler depends on the following libraries:

Glib: A general-purpose utility library, not specific to graphical user interfaces. Glib provides many useful data types, macros, type conversions, string utilities, file utilities, a main loop abstraction, and so on.
Libchenabler: a library released under the LIPS License, which provide APIs of manage call logs

Libiac: a library released under the LIPS License, which is internal library used in reference implementation for LiPS enabler. It provides mechanism of communication among different application.

liblinphone: liblinphone is a high level library to make a SIP phone. liblinphone itself relies on those parts:

eXosip, the SIP user agent library, based on libosip2
mediastreamer2, a powerfull library to make audio/video streaming and processing licensed under the GPL.
ortp, a Real-time Transport Protocol (RFC3550) stack under LGPL

2 Design & concepts

2.1 Structure

Figure 1

Figure 1 describes the Voice Call Enabler implementation which enables applications to use any of three telephony services available on the device: the circuit switched 2G/3G cellular telephony as well as a SIP elephony services.

The choice of the technology specific service to be used for a particular call initiated by an application via the Voice Call Enabler API may depend on the enabler configuration and provisioning.

2.2 Important concepts

1) SESSION

Session pattern is used in the libvocenabler.

The Session pattern requires that a client starts to use a service calling an open_session request and ends calling a close_session request. The open_session request shall return to the client an opaque session_identifier that subsequently shall be used as an input argument in any other request to the service. The session_identifier shall be wide enough to contain a pointer and is typically a 32-bits word.

2) LINE

Here, line could be understood as physical link.

Multiple lines could be simultaneously available on a phone, e.g.:

GSM line
VOIP/SIP
etc.

Applications may discover all available lines and connect to some of them.

The device management should maintain the relationship of Line and session. However, in this version of implementation, the relationship is simplified due to the lack of device management.

3) CALL

There is one call object corresponding to each outgoing, incoming or established call. A call object is designated by its call identifier – cid. Within a session a cid uniquely identifies a call object. A call object always belongs to a specific line.

2.3 Event Model

Event structure:

typedef struct {

voc_evt_type_t evt_type; /**< Event Type */

voc_cb_t cb; /**< Callback */

void* user_data; /**< Private user data */

voc_evt_data_t evt_data; /**< Event specific data */

} voc_evt_t;

The following event types are defined:

VOC_EVT_LINE – a new line is available or a previously available line in not available any more. Scope - session

VOC_EVT_LINE_SIGNAL – status of a line the application is connected to has changed. Scope – line; Event specific data – lid

VOC_EVT_LINE_CALL – a new call happens on a line the application is connected to. Scope – line; Event specific data – cid

VOC_EVT_CALL_REMOTE_STATUS, /**< an incoming call is not accepted or a connected call is remotely hungup */

VOC_EVT_CALL_STATUS – the status of a call object has changed. Scope – call; Event specific data – cid

VOC_EVT_EXCEPTION, /**< Scope: session. some error happend.

*Event specific data ('evt_data') is error code voc_err_t */

All call operations are asynchronous and return almost immediately

Asynchronous response of a call operation is sent to applications through event VOC_EVT_CALL_STATUS. Application can then use a synchronous call to query the call’s current state (next version)

Applications can choose to listen all events in a session, or events that happen to a specific line/call

3 File structures

Include/

Voc.h: a head file which include all the head files in the library for other applications to use

Vocerror.h: error definitions

Vocevent.h: event model/ APIs

Vocsession-mul.h: session, line, call operations which is Technology agnostic

Voctype.h : type definitions

Vocversion.h : version declaration.

Src/

Dbus-if.c/h : dbus related APIs. DBUS is used as IPC of communication between low APIs in Libvocenabler and Phoneserver

Shared.h: shared information about dbus between PHONESERVER and Libvocenabler

Tapi-gsm.c/h: low level APIs which transfer commands with phoneserver to manage gsm calls.

Tapi-wifi.c/h: low level APIs which transfer commands to manage WIFI calls based on Linphone library.

Vocevent.c: event APIs.

Vocsession-gsm.c/h: session, line, call operations which is related to gsm line

Vocsession-wifi.c/h: session, line, call operations which is related to wifi line

Vocsession-mul.c: session, line, call operations which is Technology agnostic

Vocsession-priv.h: internal head file which helps to realize Technology agnostic

Vocversion.c: version declaration