Ref No.:
Liaison with CELF Mobile Phone Profile Working Group (MPPWG)
Author(s): LiPS Architecture Working Group
Date: 04/03/2006
Version: 0.1
This document contains information which is the property of LiPS Forum. The acceptance of this document by its recipient implies, on the latter's part, recognition of the confidential nature of its content and the undertaking not to make any reproduction, no transmission to third parties, no disclosure and no commercial utilization without the prior written agreement of LiPS Forum.
Abstract:
This document is a liaison statement from the LiPS Forum’s Telephony API Working Group (TWG) to the Consumer Electronics Linux Forum’s (CELF) Mobile Phone Profile Working Group (MPPWG). LiPS Forum’s TWG is currently evaluating the applicability of CELF’s MPP telephony-related APIs to its own set of API specifications. After a first analysis of CELF’s MPP specifications, LiPS TWG contributors would like to go through some key technical questions in order to assess if both organizations can foster a common approach on Telephony APIs. The technical issues described in this document are mostly related to the programming model and functional granularity level of CELF’s MPP telephony APIs. LiPS TWG contributors would appreciate some feedback on these important questions.
Document's HistoryEdit / Ver. / Date / Status / Action / Description
0.1 / 04/03/2006 / Draft / C / Creation of the document
§ = modified chapter(s) or paragraph(s) Action = C: Creation, M: Modification, S: Suppression
TABLE OF CONTENTS
1 Introduction 4
2 Technical issues raised by LiPS Forum TWG 4
2.1 Programming Model 4
2.1.1 Asynchronous requests 4
2.1.2 Unsolicited events 5
2.1.3 Callbacks & Events 5
2.2 Functional Scope issues 5
3 References 6
4 Appendix 1: LiPS Programming Model 7
4.1 Rationale 7
4.2 Event Model 7
4.3 Asynchronous requests 8
4.4 "Connectedness" 8
4.5 Dynamic discovery / configurability 9
4.6 Extensibility 9
4.7 Memory allocation policy 10
4.8 Syntax guidelines 10
4.9 Header files naming conventions 10
4.10 LiPS APIs design patterns 10
4.10.1 Registration with a service – Session pattern 10
4.10.2 Unsolicited events – Event pattern 11
4.10.3 Asynchronous requests – Async Request pattern 13
5 Appendix 2: LiPS Coding Guidelines 16
5.1 Introduction to coding guidelines 16
5.2 Define Documentation 16
5.3 Enumeration Type Documentation 16
5.4 Function Documentation 17
1 Introduction
The Telephony Working Group of LiPS Forum has reviewed CELF’s MPP set of specifications dated March, 14th 2006 (see references below).
As presented in the past, the goal of this review is to assess the applicability of MPPWG’s APIs to the telephony service set identified by LiPS as one of the core services to be included in its specifications set.
The analysis has focused on programming model-related aspects and on functionality aspects.
The next sections include technical issues to be addressed for convergence of LiPS TAPI WG and CELF MPP WG specifications to converge.
2 Technical issues raised by LiPS Forum TWG
This section outlines the technical issues raised by LiPS members as an obstacle to the convergence of CELF’s MMPWG APIs and the LiPS specifications in the telephony area.
2.1 Programming Model
The major issues we found during the review are related to the programming model. We think that before talking about the APIs themselves we should agree on those points, as there are the bases of the specification.
2.1.1 Asynchronous requests
The new set of specifications does define how the client can register to unsolicited notification through callback, but it does not define how are asynchronous requests initiated and also how the clients detect their completion. Indeed, none of the Circuit Switched and Packet Switched Services have asynchronous APIs.
Allowing APIs to be processed in an asynchronous manner is really important as many telephony related APIs calls involve long processing operations (e.g. searching for available PLMNs, reading the content of a file stored in the SIM card…). The LiPS TWG will propose asynchronous facilities to all the APIs that interact with the radio stack (including SIM card) and the network (see Section 4.3).
In addition, supporting asynchronous calls will imply to add a request identification parameter to all affected APIs. This parameter will allow the callback to identify which specific request has been completed. It also will allow to set up an asynchronous request cancellation mechanism.
2.1.2 Unsolicited events
The CELF MPP API registration to the unsolicited events is service specific and relies on bit mask. This method, as mentioned in the prior liaison document, makes the API more difficult and degrades the readability. The LiPS TWG approach is based first on the ability for an application to register either to all the events belonging to a specific service or to register to all the telephony events. Secondly, another generic API will allow the application to register to a single unsolicited event no matter of the service it belongs to. Therefore it will be possible to specify a callback for a specific event or for a set of events.
2.1.3 Callbacks & Events
The CELF MPP programming model specifies that the server monitors the events and as soon as one of them occurs it calls the client callbacks in the process context of the client. No more information is given regarding how this is achieved as it is not covered by the specification. This point is very important as the way this is implemented will vary between implementations and will introduce specific mechanism/behavior with which the applications will have to deal.
From the LiPS specification perspective, it has been decided that the client will be in charge of checking whether there is a pending event or not. As the event structure contains above all the pointer to the callback there is no issues with the context of its execution. In addition, this mechanism simplifies the development of applications with UI as the event loop can be shared.
2.2 Functional Scope issues
We understand the functional scope of CELF MPP API to cover:
- Circuit-Switched Communication Services (3G) [3]
- Packet-Switched Communication Services (3G) [5]
- Short Messaging Service [6]
- Lighting Service [8]
- Equipment Service [7]
LiPS Forum TWG members still believe that some major parts of “Equipment Service” (e.g. keypad, alert) should not be covered by Telephony specifications as there are related to other domains of specifications such as UI services, audio framework, power management; or even specific to the design of the terminal’s MMI….
Similarly, the “Lighting Service” should be covered as part of a more generic hardware-related framework.
The other communication services should be more closely reviewed to also cover the needs of 2G/ 2.5 G devices and not just 3G devices. Moreover, several other services should be covered:
- SIM Application Toolkit
- Security (Facility Locks, PIN Codes)
- Unstructured Supplementary Services Data
- Supplementary Services
- Phonebooks (Radio internal and SIM card ones)
3 References
[1] “LiPS Reference Model”, LiPS Forum Architecture Working Group, version 0.4, 10 February 2006.
[2] “Linux based 3G specification – Multimedia Mobile Phone API - Preface”, CELF Mobile Phone Profile WG, Doc#: CELF_MPP_Preface_FR1_20060301 (MppApiPreface-FR1.pdf), March 1st 2006.
[3] “Linux based 3G specification – Multimedia Mobile Phone API – Reference Architecture”, CELF Mobile Phone Profile WG, Doc#: CELF_MPP_RA_FR1_20060301 (MppApiRefArch-FR1.pdf), March 1st 2006.
[4] “Linux based 3G specification – Multimedia Mobile Phone API – Circuit-Switched Communication Service”, CELF Mobile Phone Profile WG, Doc#: CELF_MPP_CS_FR1_20060301 (MppApiCs-FR1.pdf), March 1st 2006.
[5] “Linux based 3G specification – Multimedia Mobile Phone API – Packet-Switched Communication Service”, CELF Mobile Phone Profile WG, Doc#: CELF_MPP_PS_FR1_20060301 (MppApiPs-FR1.pdf) , March 1st 2006.
[6] “Linux based 3G specification – Multimedia Mobile Phone API – Short Message Service”, CELF Mobile Phone Profile WG, Doc#: CELF_MPP_SMS_D_2.2_20051121 (MppApiSms-2.2.pdf), 21 November 2005.
[7] “Linux based 3G specification – Multimedia Mobile Phone API – Equipment Service”, CELF Mobile Phone Profile WG, Doc#: CELF_MPP_ES_D_V2.2.2_<20051031> (MPP-API-equipment-2.2.2-preece-notes.pdf), 31 October 2005.
[8] “Linux based 3G specification – Multimedia Mobile Phone API – Lighting Service”, CELF Mobile Phone Profile WG, Doc#: CELF_MPP_PS_D_v2.2.2_20051114 (MppApiLamp_2.2.2.pdf), 14 November 2005.
4 Appendix 1: LiPS Programming Model
The sub-sections 4.1-4.8 of this section captures the needs and the scope of API design patterns to be used by LiPS Technical WG working on new APIs specifications, whereas the sub-section 4.10 describes those patterns.
4.1 Rationale
In the scope of its activities, the LiPS Forum may need to specify APIs of services for which no "standard" API is available from e.g. other bodies (e.g. OSDL, IEEE...) or from open-source projects (e.g. GTK).
Examples of such services include: telephony, OMA enabler services (Messaging, Browsing ...).
In order for these APIs toform acoherent set from the developer point of view, LiPS needs to define a number of guidelines that the API specifications produced by LiPS will follow.
These guidelines cover areas like:
· Event Model
· Synchronism
· Connectedness
· Dynamic configurability
· Extensibility
· Memory allocation policy
· Syntax guidelines
4.2 Event Model
Most services will involve the need to manage events that happen in an unsolicited manner (e.g. incoming phone call) or requests that complete asynchronously and therefore require to notify the caller after through some event (see also "Synchronism" below).
Different programming models are possible for managing such asynchronous events:
1. Callback functions registered by the clients of the interface
2. Specific (synchronous) requests to collect events. In addition a mechanism could be provided to notify the client that some pending events are available (e.g. a file descriptor that client can poll using select() system call); otherwise, a special thread should be used to collect incoming events.
4.3 Asynchronous requests
Asynchronous requests are needed in the case of transactions that take a "long" time to complete (e.g. search for available wireless networks or search through the SIM addressbook) and when the client wish to perform some unrelated (e.g. start another transaction) or related (e.g. cancel a transaction in progress or request a progress status report) action avoiding creation of another thread.
Any function exposed by a LiPS service could potentially exist in two forms: synchronous and asynchronous. The decision about whether a given function needs to be synchronous only, asynchronous only or both belong to the API designer. Nevertheless, if a function is specified as an asynchronous request or has both forms a common specification pattern must be followed.
4.4 "Connectedness"
In order to enable concurrent access to a LiPS service by several clients at a time and/or to efficiently enforce a security policy related to the client rights to access a service, it may be necessary for clients to register with the service ina client-server model.
[Note that server here and below means the service implementation]
An example is for instance an SMS service which may need to be accessed concurrently by the WAP stack to handle MMS notifications, by the Java Virtual Machine to handle MIDLETs downloaded over SMS and by the Message editor.
In the LiPS APIs, concurrent access could be handled in several ways:
1. connected mode: all applications have to register ("connect") withLiPS services in a client-server fashion.
2. disconnected mode: applications do not need to "connect" either because
a. the service is intrinsically stateless or because
b. the client provides all client related state in each call.
On a case by case basis the "connectedness" requirement for a specific service must be assessed.
4.5 Dynamic discovery / configurability
Different LiPS devices may not offer the same level of features (e.g. support ofCell Broadcast services, etc.) or capabilities (e.g. capacity of SIM phonebook,etc.).
On the other hand, it may be desirable that a LiPS application be able to run without the need of being rebuiltfor different devices.
Therefore, it may be desirable to introduce APIs to dynamically discover the capabilities / features of LiPS services available on a device.
The decision of whether for a particular LiPS service a dynamic discovery of features makes sense should be taken by the service designers.
If a feature discovery interface is provided as a part of a particular service API it should follow a "standard" LiPS "feature discovery" pattern.
An alternative approach could consist in specification of a Service Discovery API (e.g. as a part of Platform Management Services) that allows applications to query the platform about the services (APIs) available on the platform and their features.
Furthermore, whatever the approach will be adopted by LiPS to query available features, a standard pattern to describe those features should also be adopted.
4.6 Extensibility
LiPS services specifications will offer a certain level of features. For instance, the initial release of LiPS specifications may not include APIs to control advanced features of 3G bearers. However, a device implementer may want to extend the LiPS service set using a generic extension capability offered by the LiPS platform.
An implementation may provide extensions of services and even some (ioctl() like) APIs to invoke those extensions. Nevertheless, those extensions and even the APIs and mechanisms that make those extensions available for applications will be out of the scope of LiPS: an application that uses non-standard APIs will not be able to run on any other LiPS-compliant platform which does not implement those extensions even if the extensions are invoked through some standard APIs.
For example if the Telephony API provides a generic function to send some custom AT commands to modem, even if the function is implemented on all LiPS platforms the application that uses this function will run only on devices which support those custom AT command.
In other words there is no reason to standardize a mechanism to introduce and use non-standard extensions.
4.7 Memory allocation policy
LiPS APIs extensively manipulate data structures between applications and services. Consequently, a standard policy for the allocation and freeing of the memory is required.
The following policy is proposed: