Editing Documentation/Maemo For Symbian Developers Guide/Maemo and Symbian OS Concepts

== Programming languages and libraries ==

Symbian developers must obey a lot of coding conventions to write code correctly. In Maemo this is no longer necessary because Maemo uses standard C and C++. Most software developed for the Maemo platform is written in C. This software widely uses GLib utility library that provides the object model adopted for Maemo (<code>GObject</code>). However, C++ applications can also be written since there are several C++ bindings available for different libraries in the Maemo platform. Despite these bindings, C library calls should be made in code written for the Maemo platform sooner or later due to the fact that most part of the platform uses standard C and GLib. Due to Open C/C++, the Symbian developer should already be aware of the use of these libraries as well as STL, boost, and other C/C++ libraries.

== Symbian OS essential concepts ==

=== Naming guidelines ===

Symbian OS naming conventions like class names prefix (<code>C</code>, <code>M</code>, <code>R</code>, or <code>T</code>), function leave indication (<code>L</code> suffix) are left behind when programming for Maemo platform. In Maemo, the developer is given more freedom and there are no mandatory prefixes in class names. Although there are no strict rules to be followed, Maemo has some programming guidelines that should be considered. Some examples are given below:

Descriptive, lower-case names should be used for variables and functions. Underscores (_) can be used to indicate word boundaries. Non-static and unnecessary global names should be avoided. If it is absolutely necessary to employ a global variable, type or function, one should use a prefix specific to the library or module where the name is, for example <code>gtk_widget_</code>.

Local variables should always be favoured over global variables, that is the visibility of a variable should be kept at a minimum. Global variables should not be used to pass values between functions: this can be performed with arguments. Note: Global variables require extra care when programming with threads. Thus, these should be avoided.

=== Runtime type information ===

=== Exceptions ===

Symbian/C++ developers are familiar with concepts like ''leaving'' and ''trap harness'' because standard [http://www.cplusplus.com/doc/tutorial/exceptions/ C++ exceptions] did not exist when Symbian OS was originally developed. Only from Symbian OS v9 onwards C++ were exception mechanisms supported, although they still should not be mixed with Symbian/C++ code. In Maemo the standard C++ exceptions (<code>try</code>, <code>catch</code>, <code>throw</code>) are available.

=== Cleanup stack ===

A Symbian/C++ specific concept that is not available in the Maemo platform. Similar functionality can be achieved by using [[:wikipedia:Auto_ptr|auto_ptr]] class which is also available for Symbian v9 onwards. <code>auto_ptr</code> is a [[:wikipedia:Smart_pointer|smart pointer]] implementation in [[:wikipedia:Standard_Template_Library |C++ Standard Template Library]], and it is a good way to prevent memory leaks in case of exceptions ([http://maemo4mobile.garage.maemo.org/snippet_autoptr.html view example]).

For more information on using the <code>auto_ptr</code>, see the article [http://www.gotw.ca/publications/using_auto_ptr_effectively.htm Using auto_ptr Effectively].

== Class construction ==

The Symbian OS documentation states that if a class has to allocate memory, it should be derived from <code>CBase</code>. In Maemo, there is no such base class. This design causes some differences.

=== Class inheritance ===

In Symbian/C++ multiple inheritances are only allowed when combining multiple M-classes and one <code>CBase</code> derived class. This is the same approach adopted by Java that allows multiple interfaces implementations and only one class derivation per class. The reason is that multiple inheritances can become too complicated. Maemo does not impose any limits to the inheritance mechanism, so the developer has more freedom as well as more responsibility.

=== Two-phased construction ===

<source lang="cpp">class MyInnerClass

};

{

auto_ptr<MyInnerClass> m_inner;

};

{

auto_ptr<MyClass> myAutoObject(new MyClass());

}

</source>

In the example above, exceptions may be thrown after the instantiation of <code>myAutoObject</code> or in the construction of <code>MyInnerClass</code>. In both cases the objects do not leak memory due to the use of the <code>auto_ptr</code> class that holds the pointer of the objects and calls the destructor in case of leave the end of scope. A good explanation can be found [http://www.parashift.com/c++-faq-lite/exceptions.html#faq-17.4 in the exceptions section of the C++ FAQ].

== Descriptors ==

The <code>Descriptors</code> class was specifically designed for Symbian OS and does not exist as such in the Maemo platform.

== Strings ==

When working with strings, instead of descriptors you can use the C-style <code>NULL</code>-terminated character arrays and methods.

=== NULL-terminated character arrays using standard C ===

[[:wikipedia:String.h|The C-style NULL-terminated character arrays and methods]] can be used to store strings only. They are not as safe because they can cause buffer overflow. They can only be used with character set based on ASCII. One advantage is that it is guaranteed to work on any platform which supports C.

=== NULL-terminated character arrays using GLib ===

GLib is extensively used in the Maemo platform, so it is good practice to use the [http://library.gnome.org/devel/glib/stable/glib-String-Utility-Functions.html GLib-provided types and methods if using character arrays], although nothing prevents the developer from using other types.

See this [http://maemo4mobile.garage.maemo.org/snippet_gchar.html gchar example].

[http://library.gnome.org/devel/glib/stable/glib-Strings.html GString] from GLib. Similar to a standard C string, except that it grows automatically when text is appended or inserted. Also, it stores the length of the string, so it can be used for binary data which contains bytes with <code>NULL</code> values.

See this [http://maemo4mobile.garage.maemo.org/snippet_gstring.html GString example].

=== String class ===

[[:wikipedia:String_(C++)|String class]] from the [[:wikipedia:Standard_Template_Library|C++ Standard Template Library]]. The <code>string</code> class resizes automatically when necessary.

See the [http://maemo4mobile.garage.maemo.org/snippet_stlstring.html STL string example].

* Low-level, C-language memory allocation and [[:wikipedia:String.h|handling]].

* <code>GArray</code> from GLib - arrays of arbitrary elements which grow automatically as elements are added.

* <code>GString</code> that works also with binary data, as it stores the data length.

* [[:wikipedia:Standard_Template_Library#Containers|C++ containers]] (for example, <code>vector</code>s and <code>list</code>s).

== Active objects and threads ==

<source lang="c">

#include <glib.h>

#define COUNT_UNTIL 2

#define TIMEOUT 2

static int counter;

GMainLoop *main_loop;

gboolean timeout_func(gpointer data)

int main(int argc, char *argv[])

{

  counter = 0;

  main_loop = g_main_loop_new(NULL, FALSE);

  g_timeout_add_seconds(TIMEOUT, timeout_func, NULL);

  g_main_loop_run(main_loop);

  return 0;

}

</source>

* [[:wikipedia:POSIX_Threads|POSIX threads]] (the traditional Unix-style operating system type)

* <code>GThread</code> from GLib

== Static data in DLLs ==

In Symbian OS version before v9 static data in DLLs was not supported. From v9 onwards static data is supported but it consumes large amounts of memory. The Maemo platform does not have this limitation. You can use, for example, global variables in your shared libraries. Note, however, that the static data is not shared between the processes.

== Platform security ==

Platform security does not exist in the Maemo platform. When installing software with the Application Manager, it only warns if the software is NOT being downloaded from the official Maemo repositories. Maemo does not have a specific scheme to enforce platform security as Symbian has. One benefit is that installing software in Maemo is more developer-friendly than in Symbian.

== Client-server model ==