Porting PJSIP and PJMEDIA Stack to SymbianOS

[Last Update: $Date: 2007-12-31 11:11:32 +0000 (Mon, 31 Dec 2007) $]

Print Friendly Page

December 2007

Carbide C++ version 1.2 is now supported for S60 3rd Edition. See the tutorial on Building and Debugging PJSIP on Symbian S60 3rd Edition Device using Carbide C++.
 

S60 3rd Edition SDK

This is the main target of the porting effort, therefore it's the one that will be most tested. Versions of SDK that have been tested are:

• S60 3rd Edition
• S60 3rd Edition MR (Maintenance Release)

Other versions may work, but we have not tested them.

S60 3rd Edition SDK can be downloaded from Forum Nokia website, in S60 Platform SDKs for Symbian OS, for C++ page.

UIQ 3.0 SDK

The initial porting effort was done on UIQ SDK 3.0 and it worked. More over PJ doesn't use any features provided outside Symbian OS standard features, so it should work with any Symbian OS SDK (with the exception of audio device abstraction, which currently uses Audio Streaming API/plug-in and this may not be available on certain Symbian SDK).

UIQ 3.0 SDK can be downloaded from UIQ Developer Community website.

Command Line (ABLD)

The Symbian command line build system is supported for both S60 and UIQ SDK.

CodeWarrior for Symbian OS 3.1

CodeWarrior is supported, but be aware that Nokia has announced that developers will not be able to purchase new licenses after 2007. Developers working on S60 SDK should probably use Carbide C++ instead.

Visual Studio 6

Both command line and VS6 are supported for development with UIQ 3.0 SDK.

Carbide C++ version 1.2

Carbide C++ is now supported. But please note that version 1.0 will not work with PJSIP, and version 1.1 was not tested.

Carbide C++ Express Edition is free, but developers who want on-device debugging will need to purchase the Developer edition license for about 300 Euros (21 days evaluation is available).

Carbide C++ can be downloaded from Forum Nokia: Carbide Development Tools for Symbian OS C++ page.

• pjlib.mmp, the platform abstraction and framework.
• pjlib-util.mmp, for text scanner, encryption, DNS, XML, etc.
• pjnath.mmp, for STUN, TURN, ICE, etc.
• symbian_audio.mmp, Symbian audio device abstraction implementaton.
• pjmedia.mmp, the media framework (codec, conference bridge, RTP/RTCP, and the likes).
• pjsdp.mmp, part of pjmedia related to SDP.
• pjsip.mmp, SIP core stack.
• pjsip-ua.mmp, SIP user agent functionality.
• pjsip-simple.mmp, SIP SIMPLE for presence, IM, etc.
• pjsua-lib.mmp, the high level user agent library integrating SIP, media, and NAT.

• pjlib-test.mmp, for testing pjlib under Symbian.
• symbian_ua.mmp, the simple, command-line based SIP user agent application for Symbian.
• symsndtest.mmp, for testing the sound device abstraction.

c:\> cd $(PJDIR)
c:\> cd build.symbian
c:\> set EPOCROOT=\Symbian\UIQ3SDK\
c:\> 00.bat
c:\> 01.bat gcce urel

• Run CodeWarrior for Symbian OS
• Import each .MMP file into CodeWarrior project:
  1. Select File ==> Import Project from .mmp File..
  2. Select the appropriate S60 SDK from "Symbian Importer - SDK Selection" dialog, and press Next.
  3. Browse the .mmp file to import from $(PJDIR)/build.symbian directory, leave other settings unchanged, and press Next
  4. Leave "Default Symbian Project Import Template", and press Finish
  5. CodeWarrior will create a project from the .mmp file.
• Build the project by selecting Project ==> Make from the menu.
• Repeat above steps for other libraries (as listed in Library List above).

• selecting Edit ==> WINSCW UDEB Settings from the menu,
• select Target ==> Runtime Settings from the tree,
• browse symbian_ua.exe executable from the right pane.

Threading is Not Supported

Multithreading is not supported. Applications MUST run on a single thread only.

No Polling

Polling is not necessary for Symbian, since ioqueue and timer heap are implemented as Active Objects. Application just needs to call CActiveScheduler::WaitForAnyRequest() to poll the whole application (not only PJ) in a single place.

Sources are Compiled as C++ Sources

Because PJLIB's PJ_TRY/PJ_CATCH framework is implemented with C++'s try/catch construct, all sources which include <pjlib.h> or <pjlib/except.h> MUST be compiled as C++ source. Practically, now all libraries are compiled as C++ sources.

Constant global variables are evil!

For Symbian 9 (S60 3rd Edition included), the libraries may be built as .DSO (Dynamic Shared Object, Symbian term for Dynamic Link Library/DLL). This is controlled by the #ifdef macro in the .MMP files.

With .DSO, Symbian does not really want us to use (const) global variables. If we try to access these variables (that are exported from a .DSO) from application, we will get garbage values since the variables are not initialized properly.

Unfortunately, the libraries do have some (const) global variables. Things like PJ_VERSION, PJ_AF_INET, PJ_SOCK_STREAM, they're all const global variables. So Symbian application can no longer access these const global variables anymore. Instead, it must access these variable through their accessor functions (for example, pj_get_version(), pj_AF_INET(), pj_SOCK_STREAM(), etc.)

PjSymbianOS Singleton Class

File: src/os_symbian.h, src/os_core_symbian.cpp

The PjSymbianOS class is a singleton class to keep global objects such as RSocketServ and RHostResolver instances, and is initialized in pj_init() function. This class also provides other utility functions such as Unicode conversion and socket address conversion between Symbian's TInetAddr and PJLIB's pj_sockaddr_in.

Threading, Synchronization Objects, and Thread Local Storage (TLS)

File: src/os_core_symbian.cpp

For this initial porting effort, it was decided that threading will not be supported, which means that pj_thread_create() will always return failure. Synchronization object APIs (such as mutex and semaphores) are implemented as dummy functions which always return success. Thread local storage (or thread specific data) and atomic variables are supported with emulation, since these functionalities are needed by upper layer libraries.

The decision to disable thread support was made to enable building the libraries as static libraries. If PJLIB has to support Symbian threads, it has to use the Dll namespace, which can only be used by DLL targets.

In the future, it is possible that PJLIB will provide "virtual" threading (cooperative multitasking) by using Active Objects, however it is unlikely that this will be implemented in this first release.

Address Resolution (gethostbyname())

File: src/addr_resolv_symbian.cpp

The address resolution API provides pj_gethostbyname() function to resolve host's IP addresses. The function uses Symbian's RHostResolver::GetByName() API to perform the resolution. A global RHostResolver instance is kept by PjSymbianOS singleton object.

Exception Framework (PJ_TRY, PJ_CATCH_ANY)

File: include/except.h, src/exception_symbian.cpp

This is one of the major pain in the porting effort. Symbian OS does not support setjmp()/longjmp() very well, and there is no equivalent exception handling framework for the C language (many articles wrongly say that Symbian's Leave/Trap mechanism is equivalent to setjmp()/longjmp(), but clearly it's not!).

The only working solution now seems to map PJ_TRY/PJ_CATCH into C++'s try/catch mechanism. Not all PJLIB's exception constructs are supported, however. For this release, PJ_CATCH macro is not supported (only PJ_CATCH_ANY is supported).

As the implication of this, all sources have been patched to compile cleanly as C++ programs.

Socket Address Byte Ordering

File: src/sock_symbian.cpp

IP address and port in pj_sockaddr_in are stored in network byte order, consistent with other PJLIB targets. These values will be converted to host byte order when PJLIB needs to call Symbian native socket API (and vice versa).

Socket API

File: src/sock_symbian.cpp

PJLIB socket API provides BSD style abstraction for performing socket operations, such as pj_sock_socket(), pj_sock_bind(), pj_sock_send(), pj_sock_sendto(), pj_sock_recv(), pj_sock_recvfrom(), etc. The implementation for SymbianOS is provided in src/sock_symbian.cpp file.

The pj_sock_t socket descriptor is mapped to CPjSocket class (declared in src/os_symbian.h file), which is a class to wrap Symbian's RSocket. The CPjSocket class abstraction is needed because pj_sock_t needs to work with PJLIB's select() API, which Symbian doesn't provide.

Note that there is 1500 bytes compile time limitation on the receive buffer when the socket is used with pj_select(). This limitation only affects the socket when it's used with pj_select(); there is no such limitation when the socket is used directly (with pj_sock_recv() or pj_sock_recvfrom()) or when IOQueue is used.

Socket select() API

File: src/sock_select_symbian.cpp

PJLIB implements select() abstraction with the usual pj_sock_select() API.

Note that it's not recommended to mix pj_select() call with IOqueue call, since when pj_ioqueue_recv()/pj_ioqueue_recvfrom() is called, the flag and socket internal buffer used by select() will be cleared, and this will cause packet already received to be dropped..

IOQueue

File: src/ioqueue_symbian.cpp

The PJLIB's IOQueue is reimplemented for Symbian OS. Currently only socket receive and socket accept are implemented asynchronously (non-blocking); socket connect() and socket sending operations are done synchronously (blocking).

Timer Heap

File: src/timer_symbian.cpp

The timer heap is reimplemented to use Symbian's Active Object.

OS Error Reporting

File: src/os_error_symbian.cpp

This file contains function to retrieve the error string associated with Symbian error codes.

Pool Allocation Backend

File: src/pool_policy_new.cpp

The default memory allocation/deallocation backend for SymbianOS is using new/delete operator instead of the traditional malloc()/free().

Unicode

File: src/unicode_symbian.cpp

Unicode - ANSI conversion is implemented with Symbian CnvUtfConverter::ConvertToUnicodeFromUtf8 and CnvUtfConverter::ConvertFromUnicodeToUtf8 functions.

vsnprintf (Lack Of)

File: src/compat/string_compat.c

Since there's no vsnprintf function in Symbian, an implementation is provided which just maps the call to vsprintf.

No SDP

The SDP related functionalities have been put into PJSDP library, separated from PJMEDIA (to allow PJMEDIA to be compiled as C project rather than C++ project).

Sound Device

Sound device abstraction also has been split into separate project (e.g. symbian_audio.mmp and null_audio.mmp) to allow target specific sound device implementation.

No Polling

There are couple of places in pjsua_core.c where pjsip_endpt_handle_events() call is replaced by pj_thread_sleep(), since there is no polling for Symbian.