Running the Android emulator directly from the MoSync IDE

In this MoSync tutorial, Miles shows you how to configure and run the Android emulator directly from the MoSync IDE.

Building an Example and Testing on a Device

This screencast shows how to build a demo application (MoTris), how to run it in the emulator, how to select a device, and how to create a package for it.

An HTML5 Application for Android and iOS in 90 Seconds

In this MoSync tutorial, Mikael discusses how to import an example project into MoSync, and how to send it to a mobile phone.

WebViewLoveSMS

Android and iOS

It is fun to send text messages with smileys to friends and loved ones. But it is time consuming to type in lots smileys on a phone. WebViewLoveSMS is an app you can use to easily send messages with lots of heart or kiss smileys to your loved one.

This example is included in the MoSync SDK installation in the /examples folder. For information on importing the examples into your workspace, see Importing the Examples.

You will find the latest version of the source code of the app at the MoSync GitHub repository.

Behaviour

When this application starts up, the user is shown the main screen where the telephone number of the loved one can be entered.

There are just two buttons. Tapping either button send a 140-character SMS to the loved one. The Send Eternal Love button sends a repeated string of "<3" characters. The Send Warm Kisses button sends a string of ":-*" characters.

The phone number is stored on the device and will be displayed next time the application is started. (Just one phone number saved — because, after all, this is an application to be used with your loved one...)

In the Code

This example application is implemented in HTML and JavaScript, and uses the MoSync Wormhole Library to access device services from JavaScript via C++. The Wormhole Library is used for sending text messages and storing data on the device, services that you normally cannot access from JavaScript.

Here is the JavaScript code used in the app for sending a text message:

bridge.messagehandler.send( { messageName: 'SendSMS', phoneNo: GetPhoneNo(), message: textMessage }, null); 

bridge is a JavaScript library used in the application, which enables sending messages to C++. In the above example, the message consist of a dictionary with the message names, and a callback function, which we are not using, and therefore set to null.

Here is the C++ code in file WebViewLoveSMS.cpp for SendSMS message:

void handleWebViewMessage(WebView* webView, MAHandle urlData) { WebViewMessage message(webView, urlData); if (message.is("SendSMS")) { savePhoneNoAndSendSMS( message.getParam("phoneNo"), message.getParam("message")); } ... }

In file WebViewLoveSMS.cpp you find the class LoveSMSMoblet, which inherits WebAppMoblet, a central class in the Wormhole Library. The WebAppMoblet class automatically creates and configures a WebView widget (a widget in the MoSync Widget API) for the application. It listens for events from the web view and calls method handleWebViewMessage when messages are sent from JavaScript.

The file /LocalFiles/js/bridge.js is the JavaScript end of the Wormhole, and contains functions for communicating with C++. Note that WebAppMoblet is not depending on bridge.js, there could be other JavaScript libraries created to communicate with the moblet.

Class WebViewMessage is also part of the Wormhole Library and parses the data recieved from the web view. Currently the message format is based on RESTful URLs.

Support for parsing other formats, like JSON, could be added, either to class WebViewMessage, or to a subclass of it, or to an entirely new class. The idea is to provide flexibility in how to commuicate between JavaScript and C++.

Fun things to do

A great way to learn how to author HTML5 applications in MoSync is to modify the LoveSMS app in various ways. You can easily change the background image and the color of user interface elements, to create your own personal unique look for the app. Check out this blog post for further details. 

WebViewTwitter

This example application is a simple Twitter client that shows tweets by selected users. Users can be added to a Favorites List stored on the device. The app uses the jQuery JavaScript library and its jQtouch plug-in, and the MoSync Wormhole C++ Library.

Tweet Reader screen (Android)	User tweets screen (Android)

This example is included in the MoSync SDK installation in the /examples folder. For information on importing the examples into your workspace, see Importing the Examples.

Behavior

When started, this example application displays the main application screen headed "Tweet Reader". On this screen the user can enter the username of a Twitter user. On tapping View Tweets by this user, a second screen is displayed showing that Twitter user's recent tweets.

On the main application screen the user can also add the Twitter user's username to a Favourites List, or tap on an entry in the Favourites List to go straight to that person's tweets.

In the Code

The following technologies are used in this application:

• HTML5, Javascript, and jQtouch for the design the main user-interface elements and handling of UI events.

• The JQuery getJSON function to call the Twitter API and parse the JSON document that is returned as a result.

• The MoSync Bridge Library ( bridge.js) to connect to Wormhole Library.

• MoSync Wormhole Library for bi-directional communication between MoSync C++ code and HTML5/JavaScript pages.

• MoSync File API (C++) to write to and read from the device's file system.

Included in the example is a set of wrapper functions for accessing the MoSync File API from Javascript (file.js).

WebViewTwitter.cpp is the main file. It includes an implementation of WebAppMoblet. The example application uses the MessageHandler class to process and respond to messages coming from JavaScript.

All of the HTML5 and JavaScript-related files and libraries are located in the /LocalFiles directory, are included in the application when it is built in the MoSync IDE.

The /Resources.lst file has a default entry for the bundled files that should not be removed unless the user wants to remove all the HTML5 functionality.

WebViewGeoLocation

The WebViewGeoLocation application displays your current location, as returned by EVENT_TYPE_LOCATION events. This example is useful for understanding the basic mechanisms for communicating between JavaScript and C++.

This example is included in the MoSync SDK installation in the /examples folder. For information on importing the examples into your workspace, see Importing the Examples.

You will find the latest version of the source code of the app at the MoSync GitHub repository.

Behaviour

When this application starts up on an Android of iOS device, the main screen is displayed. Touch the Start button to start tracking the current latitude and longitude of the device. Touch the Stop button to stop tracking.

In the Code

The purpose of the example is to demonstrate how to communicate between JavaScript in a WebView widget and C++ code, by using basic low-level syscalls and events.

(Other WebView examples, such as WebViewLoveSMS, demonstrate how to use the high-level MoSync Wormhole Library for such communications.)

The application is implemented in C++, HTML and JavaScript. It has an explicit event loop, rather than using a Moblet, to let you see how the basic event mechanism that handle messages from JavaScript works.

The user interface for this application is created in HTML: to keep the example code to a minimum, the example uses only very basic HTML tags and no CSS.

When the program starts, a single WebView widget is created. The HTML and JavaScript code is stored in a text file and packaged with the application as a binary resource. That resource is extracted when the program starts, and the web view is set to display that data. This is done in C++ code, in file WebViewGeoLocation.cpp.

The communication mechanism for invoking C++ code from JavaScript is based on a URL hook. In file WebViewGeoLocation.cpp, the following URL hook is installed when the web view is created:

maWidgetSetProperty(
    webView,
    MAW_WEB_VIEW_HARD_HOOK,
    "mosync://.*");

This will cause all urls with the scheme "mosync://" to be detected by the WebView, and rather than loading a new page, a widget event of type MAW_EVENT_WEB_VIEW_HOOK_INVOKED will be sent to the MoSync event queue.

In file /Resources/GeoLocationPage.html, the following JavaScript code is evaluated when clicking the Start button:

document.location = "mosync://StartTrackingGeoLocation";

The result will be that the url is "hooked", and the following C++ code in WebViewGeoLocation.cpp is called:

case EVENT_TYPE_WIDGET:
    handleWidgetEvent((MAWidgetEventData*) event.data);
    break;

In the handleWidgetEvent method the following code gets called, which causes location tracking to start, and location events to be sent to the event queue:

if (0 == message.find("mosync://StartTrackingGeoLocation"))
{
    maLocationStart();
}

When a location event is sent, the following code is used to communicate the location back to JavaScript to update the web page:

case EVENT_TYPE_LOCATION:
    handleGeoLocationEvent((MALocation*) event.data);
    break;

void handleGeoLocationEvent(MALocation* location)
{
    char script[512];
    sprintf(
        script,
        "javascript:GeoLocationUpdated('%f','%f');",
        location->lat,
        location->lon);
    maWidgetSetProperty(mWebView, "url", script);
}

Calling maWidgetSetProperty on a WebView widget, with the property "url" set to a string that has the "javascript:" scheme will cause that JagScript code to be evaluated in the web view.

In this way, by hooking URLs in a web view and setting the "url" property of a web view, you can communicate asynchronously between JavaScript and C++ code.

It should be noted that the above code snippets use low-level mechanisms that may not be avaiable on all future platforms MoSync will run on. While they work file on Android and iOS, the facilities provided by the WebView widget varies between platforms, and some platforms may not provide url hook capabilities, for instance. If this is the case, you cannot use "document.location" to set a url with data that is hooked by the web view. You then need to use other techniques to send data between JavaScript and C++. The higher-level Wormhole library will encapsulate and abstract away these low-level details and differences between current and future platforms supported by MoSync.

Related documentation

• Example WebViewLoveSMS (example that uses the Wormhole library)
• How to create an HTML5 project in MoSync
• How to communicate between JavaScript and C++ in MoSync (explains the Wormhole library)

The JavaScript/Lua Bridge Explained

In this video, Iraklis and Mikael demonstrate the JavaScript/Lua bridge. Lua, like JavaScript, is a dynamic language, which means that we can evaluate code on-the-fly. We evaluate Lua from JavaScript by sending messages with Lua scripts to the underlying Lua application hosting the WebView. View the full tutorial.

Creating Your First C/C++ Application

This tutorial walks you through the creation of a simple "Hello World" application in C/C++ using the MoSync IDE and introduces you to some of the basic terminology we use throughout our guides, tutorials, and examples.

Creating a New Project

Start by Launching MoSync. MoSync prompts you to select a workspace:

Click OK to accept the default path. The MoSync IDE will open.

Register you copy of MoSync if you have not already done so. After registration, close the Welcome page if it is showing.

Create a new project by right-clicking in the Project Explorer view then choosing New > Project: 

( If you have hidden the Project Explorer view, you can show it again by selecting Window > Show View > Other > General > Project Explorer and then clicking OK.)

When the New Project window opens, expand the MoSync folder and select MoSync Project:

Click Next.

The project name and location screen appears:



Enter the Project name "HelloWorld". (To ensure compatibility with all platforms and devices, avoid using spaces in project names. It is always safe to use the underscore character.)

Tick the Use default location box. Click Next.

A new window will open showing you the templates that are available for you new project:

For more information about these templates, see Creating Projects from Templates.

Select the MoSync Moblet Project template. Select it and click Finish.

Your new project will now be created from the template and loaded in the MoSync IDE:

Creating HelloWorld

Edit the code in the main.cpp file shown in the main window so that it looks like this:

#include <MAUtil/Moblet.h>

using namespace MAUtil;

class MyMoblet : public Moblet
{
public:

    MyMoblet()
    {
        maSetColor(0xFFFFFF),
        maDrawText(0, 32, "Hello World!");
        maUpdateScreen();
    }

    void keyPressEvent(int keyCode, int nativeCode)
    {
	if(keyCode == MAK_0 || keyCode == MAK_BACK || keyCode == MAK_SOFTRIGHT)
        {
            close();
        }
    }
    void keyReleaseEvent(int keyCode, int nativeCode)
    {
    }
};

extern "C" int MAMain()
{
    MyMoblet myMoblet;
    Moblet::run( &myMoblet );
    return 0;
};

Save your main.cpp file.

(If you would like to understand more about the code we just asked you to paste in, read our beginner's tutorial called Hello World, Deconstructed.)

Running Your Application

Your application is now ready to be built and run.

Click on your project's name in Project Explorer view so that it is highlighted.

Now click the Run button on the IDE's toolbar (or press Ctrl+F11). Your project will be built, and your application will run in MoRE, the MoSync emulator:



Congratulations, you have now compiled and executed your first MoSync program!

What Next?

In our User Guides you will find extensive information about the MoSync IDE, including how to create projects from templates, how to use device profiles, doing bluetooth discovery and transfer, and how to use the MoRE emulator, the Debugger, the Finalizer, and MoSync's tools.

In our Programmer Guides we teach how to use MoSync's classes, functions, and syscalls in your applications, and we also provide tips for creating applications that work across multiple platforms like iPhone, Android, and Windows Mobile.

Our extensive Tutorials library covers all aspects of using the MoSync SDK to creating working applications. You will find lots of helpful code snippets here, and step-by-step instructions for common coding tasks.

We provide many Example Applications in the SDK itself, so you can see how we do it ourselves. If you are new to C/C++, we strongly recommend that you spend some time examining the code of our "Hello" series of applications: they are extremely well-commented so that you can unserstand exactly what is happening in every line of code.

At our website you can find many resources for developers, including our developer forum, and links to our code repositories and issue tracking systems.

Have fun, and good luck!

HelloWorld

HelloWorld is a well-commented example for beginners of a very simple MoSync application that uses the Moblet framework. The application demonstrates how to structure the simplest possible application that responds to key events.

This example is included in the MoSync SDK installation in the /examples folder. For information on importing the examples into your workspace, see Importing the Examples.

Behaviour

When run, the words “Hello World!” should appear on an otherwise blank screen. Examine the source code of the application (in the file helloworld.cpp) to learn how the program works. We also provide detailed documentation for this example in our Hello World, Deconstructed tutorial.

Key Presses

• 0 key, back button, or right-softkey - exits the program

HelloWorld, Deconstructed

In our beginners tutorial called Creating Your First Application we skipped over many features of the "Hello World" application that we asked you to paste into the IDE. In this tutorial we are going to take a much deeper look at that code, examine the basic structure of a C++ application, and discuss some basic design decisions we have made in the MoSync approach to mobile application development.

A note to absolute beginners: C/C++ applications can be a little overwhelming at first, but with a little persistence you will soon get the hang of it. As you go through this tutorial, try typing each line into the MoSync IDE, rather than just cutting and pasting. That way you''ll get a better feel for laying out the code and getting the syntax right. As you type, you will be given interactive help by the IDE, which can be very useful. Remember to use the Moblet Project template when you create you project.

A note to experienced C++ developers: You probably know a lot of this stuff already, so feel free to skip ahead to our extensive collection of tutorials and example applications. On the other hand, if you do read on, maybe you will learn something important you didn't know about C/C++ or MoSync, like that tricky MAMain entry point....

Hello World (Naked)

Here is the code we asked you paste into the MoSync IDE in our Creating Your First Application tutorial:

#include <MAUtil/Moblet.h>

using namespace MAUtil;

class MyMoblet : public Moblet
{
public:
    MyMoblet()
    {
        maSetColor(0xFFFFFF),
        maDrawText(0, 32, "Hello World!");
        maUpdateScreen();
    }

    void keyPressEvent(int keyCode, int nativeCode)
    {
        if(keyCode == MAK_0 || keyCode == MAK_BACK || keyCode == MAK_SOFTRIGHT)
        {
            close();
        }
    }

    void keyReleaseEvent(int keyCode, int nativeCode)
    {
    }
};

extern "C" int MAMain()
{
    MyMoblet myMoblet;
    Moblet::run( &myMoblet );
    return 0;
}

Now let's take a close look at what is going on in each of these lines of code.

Including Library Classes

The program starts with a directive to include the contents of the Moblet.h header file from MoSync's MAUtil directory:

#include <MAUtil/Moblet.h>

In C/C++, header files are an important way to connect together the different files of a program. It is common practice to put the generic code that you might want to use in many places in a separate file and two create a header file that contains forward definitions (declarations of classes, functions, and data types) for that generic code. Then you use an #include statement to include the header file in your other code modules. The header file acts like an interface to your generic code. That way you can reuse your generic code in many places, but only have to make updates to it in one place. For information, see Working with MoSync Libraries.

Here we are using a header file to connect our main application file with the pre-compiled library file (mautil.lib) that contains the generic code for Moblets.

The "#" sign indicates that this directive is to be handled the preprocessor — a program that will be called by the compiler as the first step of translating our source code into an executable binary file. In this case the directive instructs the preprocessor to read in the declarations in Moblet.h. We will explain what a Moblet is, and how you use it, a little later on.

Using Namespaces

Our next statement specifies that we will be using the MAUtil namespace as the base reference for our objects:

using namespace MAUtil;

The effect of using this namespace is to say "look in the set of things called "MAUtil" to find the definitions of the identifiers I use in this program". By specifying the namespace here our code becomes more readable. If we didn't have this line, we would have to explicitly reference the scope of MAUtil objects, we would have to write MAUtil::Moblet every time we wanted to use the Moblet class.

Inheriting From a Base Class

The next thing we need to do in our application is define its classes. Here we define a new class, based on the Moblet class, called MyMoblet:

class MyMoblet : public Moblet {

Moblet is a MoSync base class - a class which is meant to be built upon to do something useful. In the C++ world, a class is essentially a set of data and functions which manipulate that data (often referred to as instance variables and methods in other object-oriented languages).  A class is a blueprint: in a running application the class is used to create actual objects (instances) as they are needed.

Usually a class represents something concrete — although it's sometimes a little hard to understand what that thing is. In the case of Moblet it represents a simplified event handler for a mobile device.

As we will see later, Moblet takes care of the application main loop for you. All you need to do is subclass it and implement functions for the events that you want to your program to respond to (such as key presses, screen touches, and new connections). A Moblet application responds to events in a consistent way regardless of the device it runs on. That means we do not need different code for an Android device, Symbian device, a Windows Mobile device, or a phone running Java ME.

To learn more about the events that Moblet can detect, and the various types of listeners you can set up, look up Moblet in the MoSync API Reference Guide in the IDE under Help > API Reference > Classes > MAUtil::Moblet.

Our new class, MyMoblet inherits all the chracteristics of the Moblet base class, and adds to it. What we will be adding are functions that will perform actions when events occur.

The keyword "public" before the Moblet identifier means that other classes and functions in our application can access all the public members of the Moblet base class when using MyMoblet. That is to say, what is defined as public in Moblet becomes public in MyMoblet, even if we don't get around to listing them in MyMoblet.

Declaring Public Members

The data members (instance variables) and member functions (methods) within a class can be either public or private. If they are in the public section of the class, they can be accessed from other classes. Here we start the list of public members of our MyMoblet class:

public:

Defining a Constructor

The first public member of our MyMoblet class is a method, the constructor. The constructor gets called when an instance of the class (an object) is created. In this case it is a parameterless constructor as we don't need to pass in any data:

    MyMoblet() {

(In the case of MyMoblet there is no destructor to clean up after the object once it has fulfilled its usefulness, simply because it would be empty. Constructors and destructors can be implicit: if you don't specify a constructor or destructor, the compiler will put it in.)

Using Syscalls

The MyMoblet constructor contains three function calls which will be executed in sequential order. (You can distinguish function calls from data members in a class because they are immediately followed by 0, 1, or more parameters in parentheses.)

These three function calls - we call them syscalls - are to low-level, device-independent functions that are defined in the main MoSync syscall header file, maapi.h. You'll be using the functions defined in maapi.h a lot in your applications, so it's worth getting to know it intimately. Read about maaip.h syscalls in the MoSync API Reference Guide in the IDE under Help > API Reference > Files > maapi.h.

The first syscall sets the colour of the output to white:

        maSetColor(0xFFFFFF);

From now on, until it is explicitly changed, all output from text and drawing commands will be displayed in this colour. Note that each statement within the method is terminated by a semicolon in C/C++.

The second syscall in the MyMoblet constructor renders the text "Hello World!" to the backbuffer at the coordinates x=0 and y=32:

        maDrawText(0, 32, "Hello World!");

The coordinates 0,0 are the top left corner of the screen. The y-axis increases as you head downwards, the x-axis increases as you head rightwards.

To make screen update flicker free, drawing is done to a so called backbuffer, which later, when everything is drawn, will be copied in to the display. Thus the text is not yet visible at this point in the program.

The third syscall is what updates the physical screen of the device with the contents of the backbuffer:

        maUpdateScreen();

If you forget this last statement, and that's easy to do, you would just see a blank screen when you ran your application!

Grouping Statements With Brackets

Curly brackets are used to group statements in C/C++. Now that we are at the end of the constructor, we close the opening curly bracket at the beginning:

    }

(The bracket that marks the beginning of the class will be closed it later on, when our class is complete.)

Detecting Key Presses

The second public method of our MyMoblet class is keyPressEvent:

    void keyPressEvent(int keyCode, int nativeCode) {

Before the name of the method, we need to state the type of the data that the method returns. In this case, the method does not return anything ("void" = nothing).

The keyPressEvent method is called whenever a key is pressed on the device's keypad. It is passed two parameters by the MoSync runtime — the runtime is that part of MoSync which interfaces with the device's operating system and which handles the syscalls from your application.

The first parameter is a device-independent code representing a key, a MAK code. Regardless of the device, if the 0 key on the device's keypad is pressed, the keycode will be MAK_0, and if the device has a back key it will be MAK_BACK.

You can find all the MAK codes in the MoSync API Reference Guide in the IDE under Help > API Reference > File Members > Defines > M.

The second parameter is device-specific (native) key code. That's needed because the MoSync MAK codes are not an exhaustive list of all the buttons ever made available on a mobile device, instead they are a common subset. Your phone may have a button which is specific to that model, for instance the volume keys or the back button on an Android phone. If you know what the value of those keys, you can act on them here.

The keyPressEvent method is one of several methods we have inherited from the Moblet base class. Here we replace (override) the method with our own version. When the program runs and an instance of MyMoblet is created, the C++ runtime system will detect that the instance has a method that replaces the method in the base class. Methods that can be overridden like this are called "virtual methods" in C++.

Closing Applications

Now we define what should happen if the zero key on the keypad has been pressed (or the back button, or the soft-right key), and in this case we are just going to exit the program using Moblet's close function:

        if(keyCode == MAK_0 || keyCode == MAK_BACK || keyCode == MAK_SOFTRIGHT)
        {
            close();
        }
    }

The close method releases any resources used by the object and ends the execution of the program.

The Moblet base class also includes a closeEvent method. That method can be used to detect a forced application close detected by the MoSync runtime on the device. By overriding it in your Moblet-based class, you can perform essential data-saving tasks - you only have a second or so! - before your application is forced to terminate by the devices OS.

Detecting Other Events

There are many other event detection methods in the Moblet base class that you can override, including pointer movements, focus changes, Bluetooth connection, timers, and so on. The keyReleaseEvent which comes next in our example is another method that you will commonly want to implement in a Moblet-based application. It isn't actually needed for this simple application, but it works in a similar way to the keyPressEvent we used above.

    void keyReleaseEvent(int keyCode, int nativeCode) {

For a complete list of the events See the MoSync API Reference Guide in the SDK under Help > API Reference > Classes > MAUtil::Moblet.)

Commenting Code

We've left a comment which you can replace with your own code for key release events:

        // todo: handle key releases - put your code here.
    }

Single line C/C++ comments are preceded by two forward slash characters // and terminate at the line end. Anything on the right side of both forward slashes would not be read by the compiler (actually the parser).

You can also use a single forward slash followed by an asterisk to indicate the start of a comment. To end the comment, type an asterisk followed by a forward slash, for example:

/* This is a comment */ 

This type of comment can be spread over several lines.

There are no private data members or functions needed for the MyMoblet class, so we can just close its definition now. Note that we need to put a semicolon after bracket that closes a class.

};

Now we have completed our definition of the MyMoblet class, which is the only class we need in this simple application. If we needed more classes, we would put them here.

Defining the Application Start Point

We move on to defining the entry point of our program. This is the place where the execution of the application starts when it is run:

extern "C" int MAMain() {

In C you always have a function called main() that is called when the program execution starts. In a MoSync application, the main() function is actually implemented in the runtime. (Remember, that's the part of the application that interfaces with the device's operating system, and hides the complexity of the OS from your application.) In your application you need to use MAMain() to mark its start point. Just think of MAMain() as a synonym for main().

Because C++ is an object-oriented programming language which includes (and is built upon) the procedurally-oriented C language, C++ programs can consist of both C++ classes (like MyMoblet) and C statements like this one. Unlike our earlier methods, this one is a C function (hence the extern "C" bit). A function is like a method, but is not associated with an object, and is defined outside of the classes in the program. In C++, you can freely mix between C and C++ but you always have to start your applications in C.

Running our Moblet Application

There is a static method in the Moblet class called run (a static method is associated with the class, not with any instance). This is what starts your application. To call the run method you need to pass it a pointer to a new instance of our MyMoblet class, so we create one with the "new" keyword:

    Moblet::run(new MyMoblet());

This constructs the MyMoblet instance and runs the code in the MyMoblet constructor.

Returning Results

C main methods should always return an integer (int), so we return 0, by which we indicate that the program has successfully ended:

    return 0;
}

And that's it. Our application is now ready to build and run.

Hello World (Fully Clothed)

/** 
* This application provides a very basic example of how to use MoSync
* to print the text "Hello World" to a device's screen. The code is very
* well commented so that you can see exactly what's happening at each step.
* The application makes use of MoSync's Moblet framework to handle events.
*
* @file helloworld.cpp
*
* @author Chris Hughes
*/

/*Include the header files for MoSync Moblets so that we can
*access the Moblet library code from our application.
*/
#include <MAUtil/Moblet.h>

/*Declare the MAUtil namespace so that we can use the short forms of
*identifiers in our code. This allows us to write, for example,  "Moblet"
*instead of "MAUtil::Moblet".
*/
using namespace MAUtil;

/*Create the wrapper for the entire application. It is here that we will manage
*the application and handle events. To create the wrapper we make our own
*implementation of the MoSync Moblet base class. There can be only one Moblet
*in an application.
*/
class MyMoblet : public Moblet
{

// Define our new class's public methods.
public:
	/*First, the constructor, which we will call whenever we need an
	*instance of MyMoblet. In this case, the constructor consists
	*of three syscalls.
	*/
	MyMoblet() 
	{
		// The first syscall sets the background colour.
		maSetColor(0xFFFFFF);

		// The second syscall writes the text "Hello World" to the backbuffer.
		maDrawText(0, 32, "Hello World!");

		// The third syscall copies the contents of the backbuffer to the
		// physical screen.
		maUpdateScreen();
	}

	/*Next, a method for detecting key presses. This is a method we have
	*inherited from the Moblet base class and here we will override that
	*method with some processing of our own.
	*/
	void keyPressEvent(int keyCode, int nativeCode)
	{
		//Close the application if the zero, back, or soft-right key is pressed.
		if(keyCode == MAK_0 || keyCode == MAK_BACK || keyCode == MAK_SOFTRIGHT)
		{
			close();
		}
	}

	// Finally, a code stub we might need to use later for another event type.
	void keyReleaseEvent(int keyCode, int nativeCode) 
	{
		// to do: handle key releases - put your code here.
	}
};

/*Now we get to the entry point for the application - the place where
*processing starts.
*/
extern "C" int MAMain() 
{
	// Create the instance of MyMoblet
	MyMoblet myMoblet;

	// Run the Moblet to start the application.
	Moblet::run( &myMoblet );

	/*MyMoblet will run until it is closed by the user pressing key 0. When
	*it's closed we end our program in a well-behaved way by returning zero.
	*/
	return 0;
}

What Next?

If you are new to C++, there are many useful references and tutorial sites on the Internet that can help you learn more. We particularly recommend the C++ language tutorials at http://www.cplusplus.com/doc/tutorial.

We have several other beginner's application examples which you can find in the MoSync IDE, for example: HelloWorld, HelloMoblet, HelloNativeUI, HelloOpenGLES.

We have a more advanced example of a Moblet application in our programmer's guide Event-Driven OO Applications, and in our tutorial Starting a New Moblet Project.

Development Models

MoSync supports several application development models. We call them the "classic procedural", "event driven, object oriented" and "full GUI-based". The model that you should choose when developing an application depends both on the type of application you are developing and your personal preference.

The Classic Procedural Model

Using the classic procedural approach means starting out with an empty main function and implementing your own main loop, including all the event handling. Examples...

The Event-Driven, Object-Oriented Model

This approach is embodied in the use of the MAUtil::Moblet class. Inheriting it lets you implement functions such as keyPressEvent() instead of explicitly implementing an event loop yourself while providing TimerListeners and IdleListeners to facilitate execution of code outside of responding to events. Examples...

The Full GUI-Based Model

Using the MAUI library, you gain access to a variety of ready-made widgets such as labels, list boxes, text edit boxes, images, and layouts. You add logic by registering different types of listeners with the widgets, thus responding to higher-level events than with Moblets - things like selection and slider position changes. Examples...

Classic Procedural Applications

In this development model you have full control over (and responsibility for) how the application behaves. This model is most suited when you are porting existing C applications, or you want full control over program flow and events .

It is important to understand how to correctly implement a MoSync event loop. There three most important points to consider are:

• Checking for events often enough. The MoSync event queue is not infinite, so if you don't check often enough you might miss events.
• Using maWait() rather than busy-waiting, to conserve CPU usage and battery power.
• Responding to and handling the close event. After a close event is posted, your application will be forcibly terminated within a short period of time. However, your application should voluntarily exit as soon as possible, having saved any important data. (Note that after the close event has been posted, no further events will be posted and most syscalls will have no effect. See syscalls in the API Reference Guide for further information on this topic.

Example: A Simple, Well-Behaved Application

#include <ma.h>
int MAMain() {
	// Application initialization goes here

	for(;;) {
		MAEvent e;
		// Wait until we have an event
		maWait(0);  
		// Process all events that have occured
		while(maGetEvent(&e)) {
			if(e.type == EVENT_TYPE_CLOSE) {
				// do cleanup
				maExit(0);
			}
			else if(e.type == EVENT_TYPE_KEY_PRESSED) {
				// It's good practise to always provide one key
				// to exit the application.
				if(e.key == MAK_0) {
					// do cleanup
					maExit(0);
				}
				// handle other key presses
			}
		}
	}
	return 0;   
}

This example only checks for key presses, but note that results of asynchronous operations are also passed as events and should be handled similarily. See the syscall reference for more information.
Working with connections in classic applications involves responding to events whose type is EVENT_TYPE_CONN. Connection operations are executed asynchronously, and these events are the way in which your application is notified of their progress, results and termination.

Example: A Classic application Using Connections

#include <maapi.h>
#include <conprint.h>
int MAMain() {
    char buffer[160];
    // Application initialization goes here.
    InitConsole();

    // Create a connection.
    printf("Connecting...\n");
    MAHandle conn = maConnect("http://www.example.com/");  // Will cause a CONNECT event.
    // The event loop.
    for(;;) {
        MAEvent e;
        // Wait until we have an event.
        maWait(0);  
        // Process all events that have occured.
        while(maGetEvent(&e)) {
            if(e.type == EVENT_TYPE_CLOSE) {
                maExit(0);
            }
            else if(e.type == EVENT_TYPE_KEY_PRESSED) {
                if(e.key == MAK_0)
                maExit(0);
            }
            else if(e.type == EVENT_TYPE_CONN) {
                if(e.conn.opType == CONNOP_CONNECT) {
                    // The Connect operation is complete.
                    if(e.conn.result < 0) {
                        printf("Connect error %i\n", e.conn.result);
                        // Close the connection, freeing resources.
                        maConnClose(conn);
                    } else {
                        printf("HTTP result %i\n", e.conn.result);
                        // Start reading data.
                        maConnRead(conn, buffer, sizeof(buffer) - 1);  // Will cause a CONN READ event.
                    }
                } else if(e.conn.opType == CONNOP_READ) {
                    // The Read operation is complete.
                    if(e.conn.result == CONNERR_CLOSED) {
                        printf("Connection closed.\n");
                        maConnClose(conn);
                    } else if(e.conn.result < 0) {
                        printf("Read error %i\n", e.conn.result);
                        maConnClose(conn);
                    } else {
                        printf("Read %i bytes:\n", e.conn.result);
                        // Zero-terminate buffer.
                        buffer[e.conn.result] = 0;
                        PrintConsole(buffer);
                        // Read more data.
                        maConnRead(conn, buffer, sizeof(buffer) - 1);
                    }
                }
            }
        }
    }
    return 0;
} 

Event-Driven OO Applications

The MAUtil::Moblet C++ class provides boilerplate event handling and produces well-behaved, resource-efficient programs. It helps provide a higher-level abstraction of program flow.

The MAUtil::Moblet class takes care of the application main loop for you. All you need to do is subclass it and implement virtual functions to respond to the events.

Example: A Basic Moblet Application

#include <MAUtil/Moblet.h>
using namespace MAUtil;
class MyMoblet : public Moblet {
public:
	MyMoblet() {
		// Application initialization
	}
	void keyPressEvent(int keyCode) {
		// Handle key presses here
	}
	void keyReleaseEvent(int keyCode) {
		// Handle key releases here
	}
private:
};
// Since this is a C++ program, the main function
// needs to be declared extern "C"
extern "C" int MAMain() {
	Moblet::run(new MyMoblet());
}

The static function Moblet::run() implements the actual event loop. When it gets events, it distributes them to all registered listeners. The Moblet, being both a KeyListener and a CloseListener, will recieve these event types. It is recommended to handle other event types by letting your moblet inherit the corresponding listener types, such as BluetoothListener and ConnectionListener.

Working with connections in Moblet-based applications involves using the ConnectionListener interface. You inherit the class and implement the connEvent() function. You can use one listener for several connections, but each connection can only be associated with one listener. Once the events are received, you should process them in the same way as in the classic model.

Example: A Moblet Application Using Connections

#include <conprint.h>
#include <MAUtil/Moblet.h>
using namespace MAUtil;
class ConnMoblet : public Moblet, public ConnListener {
private:
	// Variables survive past individual function calls.
	char mBuffer[160];
	Handle mConn;
public:
	ConnMoblet() {
		// Application initialization goes here.
		InitConsole();
		ConsoleDelay = 0;
		ConsoleLogging = 1;
		// Create a connection.
		printf("Connecting...\n");
		mConn = maConnect("http://www.example.com/"); // Will cause a CONNECT event.
		// Register for events.
		setConnListener(mConn, this);
	}
	void closeConn() {
		maConnClose(mConn);
		removeConnListener(mConn);
	}
	void connEvent(const CONN_EVENT_DATA& data) {
		if(data.opType == CONNOP_CONNECT) {
			// The Connect operation is complete.
			if(data.result < 0) {
				printf("Connect error %i\n", data.result);
				closeConn();
			} else {
				printf("HTTP result %i\n", data.result);
				// Start reading data.
				maConnRead(mConn, mBuffer, sizeof(mBuffer) - 1); 
 // Will cause a CONN READ event.
			}
		} else if(data.opType == CONNOP_READ) {
			// The Read operation is complete.
			if(data.result == CONNERR_CLOSED) {
				printf("Connection closed.\n");
				closeConn();
			} else if(data.result < 0) {
				printf("Read error %i\n", data.result);
				closeConn();
			} else {
				printf("Read %i bytes:\n", data.result);
				// Zero-terminate buffer, so it can be printed.
				mBuffer[data.result] = 0;
				PrintConsole(mBuffer);
				// Read more data.
				maConnRead(mConn, mBuffer, sizeof(mBuffer) - 1);
			}
		}
	}
	void keyPressEvent(int keyCode) {
		if(keyCode == MAK_0)
		maExit(0);
	}
};
extern "C" int MAMain() {
	Moblet::run(new ConnMoblet());
} 

MoSync for Java and C# Developers

Mobile offers developers a new world, with cool devices and nice, easy, small projects compared to that monstrous and boring enterprise code you've been doing in Java or C#, right? Right! However, there are somethings I'm going to tell you to help you move your Java/C# skill to C++ in MoSync. The reality is that both Java and C# are based on syntax from C, so you are going to be able to read C++ source code without anyone having to explain how curly braces work or reminding you to put a semi-colon at the end of the line, which is cool. Java and C# both also have a runtime environment which manages memory and performs garbage collection for you, which C++ doesn't, which isn't cool. Also, it isn't too difficult, and I'm here to guide you through the processes which will save you time and effort, and when you into trouble, the answer will probably already be here. 

As you are a Java or C# developer, then you've spent time gathering some fine object-oriented design skills, so we're not going to touch on C code here, this will be about C++ (mostly). 

This guide is in three sections, firstly a quick reminder of how C++ works, then a section of how memory management works, and finally unlearning lots of really nice design principles which are perfect for enterprise development, but will cause you grief in mobile. 

One final note: this obviously isn't an exhaustive description of how to write in C++. This is what you need to know coming from a Java or C# background to start writing C++, so don't expect this to be the definitive description. This is a quick start guide.

How C++ works.

Ok, this isn't really everything you need to know about how C++ works, this is just a reminder about how it can be different. In C#, if you want to create a new class, you right-click and give the class a name and Visual Studio creates a new templated .cs file for you. You add in a bit of functionality, and your new class is available within its namespace. The same is nearly true in C++. Normally, in C++ you will split your class into two files, a header file and a code file. The header file will normally have a .h or occasionally a .hpp extension, whilst code files will have .c (for C code) or .cpp (for C++ code).   

The header file contains the interface definition of your class, although it can contain implementation as well. In C# when you want to use a specific class you just need to simply include the namespace of the class with a using statement. In C++, you need to provide a definition of a class before you can use it. You do this by including the header file of the class in your code using #include "classname.h". The header is literally included in source code passed to the compiler. This leads to an issue which you don't get in managed environments. If you have two classes, Alpha and Beta, you can include them in your new class Gamma like this:

#include "Alpha.h"

#include "Beta.h"

However, if Beta.h itself includes Alpha.h, you will get a compilation error when you build Gamma. This will be because the compiler inserts the code from Alpha.h, then inserts the code from Beta.h, which in turn inserts the code from Alpha.h. The compiler will complain that methods of Alpha have already been defined. To prevent this, at the top of your header file, you need to add an include guard. This is a short compiler directive telling the compiler not to include the header if it has already been included. In Alpha.h you will write something like this

#ifndef __ALPHA_H

#define __ALPHA_H

When you create a new class in MoSync, the template should do this for you. You can read this as "if there isn't a token called __ALPHA_H then create a token called __ALPHA_H." At the bottom of the code there will be an #endif to round this off. You can change the naming convention if you wish, but if you write a header file from scratch, then don't forget the include guard. 

So, in your class you may want to use some classes without specifying their namespace everytime. This is a very familiar command 

using namespace <namespace>;

Note the semi-colon at the end; this is a C++ command and not a compiler directive. 

You can create your classes in a namespace in the header file, and again it is familiar

namespace MyNamespace

{

    ...

};

Again note the semi-colon at the end.  

Inside any optional namespace declaration, you can create one or more classes (or structs).

class MyClass

{

    ...

}; 

Once more, take notice of the semi-colon at the end of the class definition. 

Inside the class, you can create methods. C++ doesn't support properties in the way you may be used to. The visibility of methods is also different, as you are able (and encouraged to) define methods in groups by visibility. A class definition in a header file might typically look like this:

class Gamma

{

public:

    Gamma();

    virtual ~Gamma();

    void incrementCounter();

    int getCounter();

protected:

    int mCounter;

private:

    bool isActive;

};

So there are a few things here we can see. Firstly, there is a class definition as we've seen before. Inside this are three blocks of member definitions, ordered by visibility. In the public section, we can see a constructor for Gamma and a destructor (~Gamma()). The constructor will be called when the class is instantiated and the destructor when it is destroyed. This maybe obvious, but these are going to become very important in the next two sections of this guide. 

After the destructor, then there are two method declarations, incrementCounter() and getCounter(). We can see that incrementCounter() doesn't return any value and that getCounter() returns an integer. We've then got two members mCounter and isActive. You can if you really want define the visibility with each member, but this is unconventional. 

Creating the code to go with the header means creating a .cpp file as well. To continue this example, we could have Gamma.h and Gamma.cpp to contain the implementation.

#include "Gamma.h"

Gamma::Gamma()

{

    mCounter = 0;

}

Gamma::~Gamma()

{

}

void Gamma::incrementCounter()

{

    mCounter++;

}

int Gamma::getCounter()

{

    return mCounter;

}

Several things to notice here. Each method needs to start with the class scope Gamma::. This means that you can implement several classes in the same .cpp, but it isn't normally recommended. Secondly, methods in C++ generally start with a lower-case letter, unlike most Java and C# classes. Thirdly, C++ doesn't support properties directly in the same way as C#, you need to create a method for get and set. Finally, as you'd expect, when you create an instance of Gamma, mCounter is set to 0 in the constructor. There is actually another way to do this, and one which is generally preferred in C++ for two reasons. The constructor could look like this

Gamma::Gamma() : mCounter(0)

{}

mCounter will be initialised with a value of 0. This can be important in environments where it may be possible to access the class before the constructor has finished executing. With the initialisation as part of the constructor specification then you are guaranteed availability. Secondly, if your class defines references (more later), then these cannot be null. By specifying them in the constructor, then you can assign the reference and avoid this issue. More on objects, pointers and references soon! 

So, if my class Gamma requires other objects or functions, then the include file can be added in the C++ file, and not in the header. It is a very good rule to only have the includes you need in the header, and if the class is used entirely internally, then #include it in the cpp file.

It is possible to have objects as public members in a C++ class, for instance

class Delta

{

public:

    int counter;

};

This is as bad an idea in C++ as it is in Java and C#.  There is nothing intrinsically wrong with it, but you don't get any opportunity to clean input into mCounter, or to check that its value is only changed when it is safe to do so.

Inheritance

C++ supports multiple inheritance, that is actual base classes with actual implementation and not just interfaces. When you specify your class, you can specify which classes to inherit from, as well as the visibility of the inheritance

class Delta : public Alpha, public Beta, private Gamma

So there are two things to say about multiple inheritance in a MoSync context. Firstly, be careful. We're sure that you regularly observe SOLID design principles and the Liskov Subsitution Principle, but C++ can be a handgun. It's an incredibly powerful piece of technology, but easy to abuse. Don't get lost in inheritance. Secondly, lots of casting of your classes between interfaces and classes is slow. The device has to do looks ups to get the correct addresses to access the object according to the interface or inherited class. We'll come back to this later. 

So, those are the warnings, and here is the good news: inheritance is cool, it makes your coding easier if you've thought it through properly. Multiple inheritance means that you can use classes which in C++ are called mix-ins. You can have a little utility class which you may want to access in a variety of contexts. In C++, you can mix in this functionality directly into your class, without having the overhead of instantiating a new class to do it. Your class may be a little larger, but there are benefits in not having to create a new instance of the utility whenever you want to use it. You can also then cast classes as these mix-ins if you need to, as long as you are prepared to change your mind about this if it gets too slow. 

Interfaces in C++ are just classes, there is no 'interface' declaration. You create a class to inherit from with virtual methods. It is unusual to prefix interface classes in C++ with the letter I.

In C#

public interface Alpha

{

    public abstract void doSomething();

}

In C++

class Alpha

{

public:

    virtual void doSomething() =  0;

};

Virtual methods can be overridden, but there is no need for an 'override' command.

class Beta : public Alpha

{

public:

    void doSomething();

};

The implementation of doSomething will be the one used, as there is no implementation in Alpha. This is called pure virtual method and it can be identified by the = 0.

This is what makes it a true interface. Any class which inherits from Alpha must implement doSomething(). Alternatively, you can provide an empty method

class Beta

{

public:

    virtual void performOperation() {}

};

This method provides an empty implementation, which means that you don't have to implement the method performOperation().

Objects, Pointers and References

One of the great advantages of memory-managed environments like .net and Java is that you don't have to worry about whether objects are created in the heap or on the stack. You can go through an entire career in managed programming without ever having to worry about it. C++ is more complicated, but instead of 'complicated' most people use the word 'powerful'.  

Just to remind you, stack memory is local to the scope of the code where it was created. Heap memory is shared across the entire scope of the application. You need to consider when you create an object whether it is on the stack or in the heap. Objects on the heap need to be explicitly destroyed with the command delete. Objects on the stack will be deleted when they go out of scope. The rule with C++ generally is to only create objects on the heap when you absolutely need to. Creating objects on the heap can be much slower than creating them on the stack. When you've been working in managed environments for a while, you forget that searching for free memory in the heap is an expensive operation. Every time you use new then it has to do that search. Creating objects on the heap is necessary though when you want to be able to control their lifespan, for instance in factory classes which may create objects which have a lifespan greater than that of the factory itself. 

To create an object on the stack, simply declare it.

String myString;

To create an object on the heap, you need to use new

String* myString = new String();

The asterisk (*) here means that you have created a pointer to a String object. This is the address a particular object or interface starts. The actual position of the asterisk can vary, so you may read

String *myString = new String();

or

String * myString = new String();

The first form, with type*, is preferred and recommended for two reasons. Firstly, the command is in the format <type> <name>. The type is String pointer, and it is called myString. If you don't put the asterisk next to the type, then you are saying that myString is a String, which it isn't. Secondly the asterisk has some other meanings in other contexts.  *myString means something else, so its use is ambiguous if you declare as <type> *<name>. 

There is another type called a reference. A reference is an address like a pointer, but unlike a pointer it cannot have a null value. References are declared with an ampersand (&).

String* myString = NULL; //Is OK

String& myString; //Will cause a compiler error

References are particularly valuable as a way to pass stack objects.

String& Gamma::getHeadline()

{

    return myString;

}

In this example, myString has previously been created as an object on the stack.  getHeadine() will return a reference to myString and not pass the entire object back as a return value.

String& headline = gamma.getHeadline(); 

Shows how you can create a reference with an assignment. 

When you access methods on an object, you need to know whether it is an object or a reference, or a pointer. Members are accessed in objects and references using a period (.) e.g.

myString.clear();

When you have a pointer, you access members using -> e.g.

myString->clear();

You can covert between pointers and reference using an asterisk. Firstly, you can dereference a pointer and treat it as an object.

String* myString = new String();

myString->append("hello world", 11);

String& strref = *myString;

strref.clear();

Interesting. The asterisk is used to say "the object that this pointer points to".  

You can create pointers to objects, even if they are on the stack. This also means that having a pointer to an object is not the same as knowing that the object on the heap. This is useful when you want to use objects with methods which expect a pointer.

int Gamma::getStringLength(String* testString)

{

    return testString->length();

}

…

String hello = "Hello World";

int strLen = getStringLength(&testString);

This is a bit of a contrived example, but you can see that by using an ampersand before the object name, it is saying "the address of this object". Both String* and &testString will have the same value. 

Memory Management

Being able to create objects in both the stack and the heap, and the lack of an automatic garbage collector, means that you have to think about the lifespan of each and every object that you create and where you create it. As we've said above, create objects onto the stack wherever possible. When you create an object on the stack, it will have a scope of the lifespan of it's location.  

For instance, if you create an object in a method

void Gamma::doSomething()

{

// String will be created here

String myString;

    …

// String will be automatically destroyed and the memory

// freed because we've reached the end of the method.  We

// don't need to do anything else.

} 

Objects can also have the scope of an object. Consider this header file 

class Gamma

{

public:

    Gamma();

    virtual ~Gamma();

private:

    String mString;

};

In the second example, there will be an object called mString on the stack. It will be created when an instance of Gamma is created, and destroyed when Gamma is destroyed. You don't need to do anything else. Easy, isn't it? 

You need to be much more careful when you are creating objects on the heap. They won't be automatically destroyed when the method or object goes out of scope. Objects on the heap are really useful because of this. You can create an object in one class and pass the pointer to another class, or you can use it internally. 

There is a design pattern called Resource Allocation is Initialisation (RAII). This pattern says that when you create a class, create the objects you need in the constructor and destroy then in the destructor.

//Constructor

Gamma::Gamma()

{

// Instance heap objects you need here

myString = new String();

}

// Destructor

virtual Gamma::~Gamma()

{

    delete myString;

}

This means that although myString will be created on the heap, then when Gamma goes out of scope myString will be destroyed.   

There are many cases where this isn't appropriate though. You could have an application which needs to send complex messages between classes. Each message is of the class 'Message'. 

class Message

{

public:

    void setMessage(const char* message);

    const char* getMessage();

    void setStatus(int status);

    int getStatus();

private:

    String mMessage;

    int mStatus;

};

It’s a little class which can store a text message and a status value. We can see that when Message is instanced, a string and an int are allocated on the stack. 

Class Gamma needs to send messages to class Delta. Delta has the following method.

void Delta::receiveMessage(Message* message)

{

// Got the message

}

Objects on the heap are really powerful, but with that power comes great responsibility. Here is a quick review of some things to remember 

• If at all possible, create objects on the stack, not in the heap. Its faster and less likely to introduce a bug. 
• Normally, the class which created an object should destroy it. RAII is a good pattern. 
• Whenever you write the word 'new' think about where the word 'delete' is going to go. It has to go somewhere or you will have a memory leak. 
• When you pass responsibility for deleting an object, then add a comment to that effect so it is clear where the responsibility lies. 
• Only have one place where the object should be destroyed. If you try to destroy the same object twice, you will get a runtime error.

If you look on the MoSync forum, or in the MAP library, you will find some debug methods for creating objects. These functions replace new and delete and keep a track of which objects have been instanced on the heap and which source file did it. When your application exits on the emulator, it will report about which objects haven't been deleted. This can help you track down memory leaks. To use them, replace all of your new keywords with newobject() and delete with deleteobject().

Design Considerations and Optimization

So you've got some killer design skills for Java or .net. Maybe you've mastered IoC containers or double dispatch and you can see how they are going really help in C++. This is good, and you can certainly use these techniques, but there are some other considerations you need to keep in mind with mobile development. If you've been doing desktop or enterprise development, then you're used to working in environments which are much more powerful than mobile. You will have lots and lots of small, specialised classes which are great for working with. Each class supports multiple interfaces and has been created to perform one small task. The reality of non-managed environments and polymorphism is that creating classes is slow, and casting objects is slow. Not so slow that you shouldn't do it, or you will be waiting all the time for your application, but slow enough that if you do use design patterns which involve a lot of tiny classes, and a lot of casting between interfaces, then you may be wondering why the application isn't as speedy as you imagined. 

You will get better speed by creating fewer classes with fewer interfaces, and on the stack rather than on the heap. Flatter designs will result in faster code. Of course, this is then a trade between the design you would use in Java and the speed you want in C++, and in many instances you won't find the code slow, but if you've got routines which create lots of instances of objects (in a loop for instance), then you need to be aware of where you can improve speed. 

If you can combine classes to put methods together in the same object, then you will save memory and be faster. Better still, if you can create utility functions in C rather than C++ objects then this will be even faster. Typically factories make a good example where C code can be used, as well as utilities like decorators don't have to be in classes. Many developers on the web will tell you to code in C by default, and only use C++ and classes where you need to.

Optimizing Mobile Applications

When you develop an application you want it to be as fast and as memory-efficient as possible. And that's even more important when you are developing for mobile devices which have slower CPUs, limited memory, and limited power resources. The MoSync SDK lets you target a huge range of devices with your applications, but you should always bear in mind the limitations of the devices you are writing apps for. Here we provide some guidelines to help you optimize your application's performance, size, and power consumption.

MoSync Libraries and Tools

MoSync includes many libraries that we have carefully optimized for performance on a wide range of devices. Try to use these libraries wherever possible. In particular, if you are developing C++ applications, make full use of:

• The Moblet framework for event handling -- it keeps battery usage to a minimum.
• MoSync's MTXml parser -- it is optimized for rapid parsing of XML yet keeps memory usage to a minimum.
• The MAUI graphical user interface library -- it only redraws GUI elements that change and uses caching mechanisms to improve speed.
• The MAUtil storage classes -- String, Vector, Set, Map and HashMap are efficient when correctly used.

Code Optimization via Pipe-Tool

Pipe-Tool is MoSync's code transformation engine. It is, among other things, a code verifier and optimizer and it performs dead code elimination to produce small, efficient output files.

Pipe-Tool is automatically invoked by the MoSync IDE during the normal build process. It can also be run on-demand from the command line. The dead code elimination process is optional and still in an experimental state, but you can turn it on by enabling Activate Dead Code Elimination in your project's build settings (select Project > Properties > MoSync Project > Build Settings > Compiler Flags) or, on the command line, by passing the -elim flag to Pipe-Tool. 

Asynchronous Operations

We've chosen to not support threads directly in MoSync, but instead we have implemented all essential threaded operations asynchronously. Whenever you start such an operation, it will run in the background and send a notification in the form of an event when it's done. By encapsulating asynchronous operations in the runtime we can ensure that the behavior is consistent on all devices, and you never have to care about thread synchronization. Some platforms implement asynchronous operations internally without threads, for instance Symbian, where they strongly encourage the use of Active Objects over threads.

To keep you application responsive when it's doing a lot of computations, it is a good idea to periodically check for events. This can be done either by invoking some event handling mechanism or by using the Moblet framework, and by doing the computations in blocks so that the execution returns to the main loop from time to time. It is also necessary to make sure the EVENT_TYPE_CLOSE event is received and handled, as it indicates that the application has been forced to quit for some reason.

Dealing with Hardware Limitations

Slow CPUs

The CPUs in many mobile devices are based on the ARM architecture. The CPUs can have different clock frequencies and cache sizes, and some have no cache at all. What mobile CPUs generally have in common is that they are all far less powerful than the ones you're used to develop for on a regular PC.

Any piece of code that is going to use a lot of CPU time should be carefully optimized. Finding the right algorithm is more likely to be important than doing low-level optimizations. Also such optimizations are usually done by the compiler (in our case GCC), so it is always good to know your compiler in order to keep the amount of work to a minimum.

If you're in need of extreme performance, basic speed optimization tricks can help:

• Pre-calculate stuff
• Unroll loops when possible
• Inline small and frequently used functions
• Give as much information to the compiler as you can (const etc.).

Many mobile devices do not have a floating-point unit (FPU). Their floating-point operations are done in software. That results in much slower processing than on regular PCs. To improve performance, the best way to deal with decimals on these devices is to use fixed-point arithmetic with integers (see, for example, http://en.wikipedia.org/wiki/Fixed-point_arithmetic).

MoSync syscalls (defined in maapi.h) incorporate platform-dependant code that is optimized for the architecture they are running on. Try to use them as much as possible, even if the same functionality is possible to re-implement in other ways. This will not only make things faster, but also smaller.

Divisions may be really slow as they aren't available natively on most ARM processors. Use shifts when possible or pre-calculate reciprocal 1/x values and do multiplications instead.

If you have to read a lot of small pieces of data from a data object, try to buffer data in memory. Doing a lot of calls to maReadData may be slow.

If your application needs to read from and write to memory a lot, try to access memory as integers whenever possible. This is even more important when targeting Android and Java ME devices. XML parsing, for instance, relies on heavy use of byte accesses. Whenever possible use some more approriate binary format.

Try experimenting with different GCC optimization flags (right-click on your project and select Build Configurations > Manage > Build Settings > Compiler Flags > Additional GCC Switches). The -o3 swtich should in most cases be slightly faster than -o2, although it may slightly enlarge the size of the binary.

It's worth mentioning that if you are used to programming in Java, you tend to use as few classes as possible, due to their size and speed overhead. But C++ objects are pretty lightweight and faster than their Java equivalent so you do not need to be so restricted.

ARM Recompiler

MoSync features a recompiler that transforms MoSync code into native ARM code at start up. For CPU-intensive applications, the recompiler can provide a substantial speed boost. As of June 2010, this recompiler is available on Windows Mobile, Symbian s60v3 and s60v5. Work is in progress to bring the recompiler to s60v2 and Android. (on our MDLbenchmark test on Symbian 5th edition, the MoSync ARM recompiler increased performance by more than 300%.)

Battery Power

Battery power is drained when hardware is in use, especially the CPU. It's therefore important to optimize for performance, making the CPU complete its work faster. The syscall maWait puts the thread in suspend mode until an event has been sent, leaving the CPU for use by other threads/processes, thus using less CPU and battery power. The Moblet framework does this automatically.

Screen Size

All phones have different screen sizes. They are often very small with low resolutions, making it more important to choose graphics wisely. Fonts or images should be visible on all sizes of screens.

Data Storage

Many mobile devices have small RAM sizes and most likely a lot better permanent storage capabilities. It's important to take this into account when developing applications for them. Unloaded binaries (.ubin) and unloaded media files (.umedia) are good formats to use for resources as they will be kept in permanent storage as long as they aren't used. (For more information about these resource types, see the Resource Compiler Reference.)

Resources such as images and media files can take up a lot of space in the final package so try to keep them as small as possible. There are many free and commercial tools available for optimizing and compressing resources without noticeably reducing their quality. Generally, you should use the PNG format for images: we have ensured support for it across all capable devices (PNG is generally smaller than GIF anyway). If you have photographic images, you should to use the JPEG format. Most modern devices support it, although some of the older ones may not so it may be worth checking.

Try not to do too many small heap allocations as this will fragment the heap. The result will be slower heap allocations and more memory usage. As you code in C or C++ it's also good to verify that you haven't got any memory leaks. This can be done using a simple trick shown in MAP/MemoryMgr.h: basically you save information about in which file, function, or line every allocation is done, and remove that whenever it is freed. This information can be dumped at anytime to see what memory leaks you have.

If you have more tips about optimizing applications for mobile devices, please share them with us by leaving a comment below.

Developing Android Applications

Android developers will find much to like in the MoSync SDK. Like the native Android SDK, the MoSync SDK utilizes Eclipse as its development environment. Here we provide some advice on building Android application using the MoSync SDK.

Android Package Settings

Package settings for Android applications can be found under Properties > MoSync Project > Android for your project. Here you can set the application's package name and version code and sign the package with your credentials.

The application package name is used by the Android OS to identify your application. The default package name is com.mosync.app_<Project Name>.

The application version code is used by the Android Market to check for application updates.

Application Signing

You need to sign your Android application before it can be installed on an Android device. You can create your own self-signed certificate (see http://developer.android.com/guide/publishing/app-signing.html). Just add the information about your certificate in MoSync and your application will be signed when you build it. 

Sending Applications to Devices via USB

From within the MoSync IDE you can search for connected Android devices. Click the small down-arrow next to the icon of a mobile phone and magnifying glass on the top bar of the IDE then select Scan for Android USB device. (If your device is not found make sure you have installed the connection software which came with the device.)

Sending Applications to Devices via Bluetooth

Newer Android devices (2.1 onwards) can also send applications via Bluetooth. This is enabled on your phone. To search for Bluetooth devices, choose Scan for Bluetooth device instead. When you have selected your device and choosen a default device profile for it, you can send the application to the device.

Bluetooth is not supported by Android 1.5 and 1.6.

Background Processing

One of the more powerful features of the Android platform is its ability to let applications run in the background. However, many devices on other platforms (particularly Java ME) do not allow you to do this, they just stop working if you switch to another application. Therefore, be careful if you are creating Android applications that rely on being able to run in the background and you intend to port them to other platforms.

 Screen Resolution Support

MoSync applications built for Android 1.6 and later uses the Android manifest settings to handle all types of screen resolutions. At this time all resolutions are allowed. 

 Touch Input and Sound 

Applications based on MoSync are able to access touch and key input, and can access all the image and sound formats supported by the Android OS.

Known Issues with Android

MoSync 2.7: 

• When your application loses focus and receives an EVENT_TYPE_FOCUS_LOST your application may be killed immediately, so make sure that you don't need to do anything important in the background.
• If your application uses too much memory the Android OS sends a warning before killing the process. This event never reaches the MoSync application, so be careful not to use more resources then you need.
• You can't specify which screen resolutions your application will work with, it defaults to be supported on all screens. This will change later.
• The ARM recompiler is not yet operational on the Android platform.
• Bluetooth service discovery behaves different from the other platforms. Please check the API Reference Manual in the IDE (Help > API Reference Manual) for further information.
• Fully transparent pixels in PNG images lose their colour values when retrieved by maGetImageData.
• In maSoundPlay the parameter offset is not supported, it should be set to zero, and the audio data (starting with the mime header) should begin at the start of the data handle referenced by parameter sound_res.
• In existing Android applications, you may need to increase memory settings for heap space (possibly also total data size) in "Project/Properties/MoSyncProject/Build Settings/Compiler Flags/Heap Size" if you get an error message saying "Malloc failed. You most likely ran out of heap memory. Try to increase the heap size."
• In some rare occations there are problems with maWait( 0 ) blocking the event queue until a new event arrives. This can for example happen when doing intensive networking; it can happen that an event of type  EVENT_TYPE_CONN does not cause maWait( 0 ) to wake up and return. If you should observe this behaviour in your program (app seems to be hanging until a new event triggers), just update maWait( 0 ) to a non zero parameter, for example maWait( 100 ). This will cause maWait to wake up every 100 milliseconds, thus solving the blocking behaviour. In the upcoming MoSync 2.7.1 release, this problem will have been fixed. If you are using class MAUtil::Moblet or one of its subclasses, you should not experience this problem as the Moblet class never calls maWait( 0 ).

Developing iPhone Applications

All of Apple's iPhone, iPad and iPod touchscreen devices run the same operating system: iOS. Currently, the only way to download applications to an iOS device without voiding its warranty is via the Apple App Store. Here we provide advice on building successful iPhone apps with the MoSync SDK.

Building iOS Applications with the MoSync SDK

Apple imposes strict rules and guidelines on how applications made available through its App Store are to be built. That means to successfuly build an iOS application with the MoSync SDK, you will need to install the MoSync SDK for OS X on an Apple Mac running Snow Leopard (OS X version 10.6). You will also need Xcode 3.2.4 with the iPhone OS SDK. To build and distribute an application for anything else than the simulator you will need to join Apple's Developer Program.

If you do not have an Apple Mac available right now, you can install the MoSync SDK for Windows on an Windows machine. You will still be able to build your project, but the output will be an Xcode project which will then need to be built on an Apple Mac Snow Leopard running Xcode version 3.2.5.

Building iOS Apps with the MoSync SDK for OS X

1. Set an iOS device (iPhone, iPad, etc.) as a target device profile in the MoSync IDE.
2. Build your application. An Xcode project will be created for you.
3. Open the Mac Finder and find the Xcode project file: <ProjectDirectory>/Output/Release/Apple/iPhone/package/xcode-proj/<ProjectName>.xcodeproj
4. Double-click on the Xcode-project to open it with Xcode.
5. In Xcode, choose the target device or simulator that you want to build for.
6. Press Build and run to start the application on the target.

Building iOS Apps with the MoSync SDK for Windows

1. Set an iOS device (iPhone, iPad, etc.) as a target device profile in the MoSync IDE.
2. Build your application. An Xcode project will be created for you.
3. Open Windows Explorer and find the Xcode project file: <ProjectDirectory>/Output/Release/Apple/iPhone/package/xcode-proj/<ProjectName>.xcodeproj
4. Move the created Xcode project to an Apple Mac Snow Leopard running Xcode to finalize the application.

Apple Guidelines and Exiting an App

Apple provides detailed guidelines describing how a well-behaved iPhone application should be written.

Generally, MoSync runtimes are completely conformant with Apple's guidelines, so you should have no trouble getting your application in the Apple App Store. Note, however, that Apple expects all applications to be closed by the "Home" button on their device, and are likely to reject applications which explicitly show an "Exit" button. If you want such a button on other platforms, simply skip it on iOS:

#include <maprofile.h>
...
#ifndef MA_PROF_SUPPORT_OS_IPHONEOS
   <code for initializing an exit button>
#endif

Storing the Application's State

An application may be closed when the phone receives a call or if the application uses too much memory. Therefore one thing users rely on is that the state of an application is stored at all times, so that when the application is restarted, its state can restored. This can easliy be implemented using MoSync's store syscalls defined in maapi.h (maOpenStore, maWriteStore...). When the application receives an EVENT_TYPE_CLOSE event, make sure you write the state to a store, so that it can be restored whenever the application is restarted.

Image and Sound Support

JPEG and PNG are the supported image resource formats.SVG images, including application icons, are not supported by iOS.

The playback audio codecs are described in the iOS Reference library.

Known Issues and Limitations

MoSync 2.5, 2.6

• maLoadProgram is not supported (Apple does not permit this functionality for applications distributed through its App Store).
• No event is sent when a didReceiveMemoryWarning event is cached, so make sure you keep the amount of resources stored in memory to a minimum.
• Stores are written to and read from the /Documents folder.
• Text drawing can be a little slow because of the way Apple's Core Graphics text-rendering API works. Try to render images with text ahead of time whenever possible.
• maResetBacklight isn't implemented due to limitations in the iPhone SDK.
• maVibrate doesn't take the time argument into account (it vibrates for a while and then stops) due to limitations in the iPhone SDK).
• If you get the error "Missing Base SDK" you are probably running the wrong version of Xcode. More information here.
• For files, the Documents directory is the home directory, e.g. if you open a file with a path that
  looks like this "hello.txt" it will look for a file that is called hello.txt in the Documents directory.
  In the future you will be able to get the path to different directories like the bundle/caches/preferences directories.
• If you want to transfer files to the phone, use an application like "iPhone explorer".
  You can also add the UIFileSharingEnabled key to the application plist-file with a value set to YES
  and transfer individual files to the Documents folder using iTunes.

MoSync 2.6

• For OpenGL the renderbuffer, depthbuffer and framebuffer is automatically set up for you. It will always uses the full retina display resolution if it is available and the best color depth available. In the future this step will be configurable.

Developing Symbian Applications

When you package an application for a Symbian device, you need to specify a UID for the package. MoSync can generate test UIDs for you to use during development. Optionally, can also self-sign your packages by specifying a key file and certificate. Here we describe how to set UIDs and do self-signing.

Symbian Unique Identifiers (UIDs)

Symbian requires that each application has a UID to uniquely identify it.

When you create a project, MoSync automatically generates random UIDs for you within the range reserved by the Symbian Foundation for development and testing use. There are different ranges of these reserved UIDs in different editions of Symbian.

To view or change the current UIDs for an application, right-click on your project in the Project Explorer view, and select Properties > MoSync Project > Symbian.

If you need to, you can generate new random UIDs in the reserved range by clicking the Generate Test UIDs button.

These UIDs are intended just for use while you are doing development on your own machine. When you application is ready for public distribution, you will need to enter, in these boxes, UIDs provided by the Symbian Foundation for your application. Visit www.symbiansigned.com for more information.

Self-Signing a Symbian Application

To install Symbian applications on 3rd and 5th edition devices, they must be signed. MoSync generates a default private key file and certificate for self-signing.

If you wish to use your own key file and certificate to sign a particular application, right-click on your project in the Project Explorer view, and select Properties > MoSync Project > Symbian > Self-Signing.

(The default key file and certificate for all projects is shown in this screenshot.)

Tick the Enable Project Specific Settings checkbox. Enter the paths to your key file and certificate. In the Passkey field, enter  the password for the key file. Click Apply.

Using OpenSSL

The MoSync SDK includes OpenSSL which you can use to generated private key files and certificates. OpenSSL can be found in the MoSync /bin folder. Visit www.openssl.org for more information.

Known Issues with Symbian

MoSync 2.5:

• With the Symbian uninstaller on 2nd edition and with 3rd edition using OS 9.1 and 9.2 if you install two MoSync applications on the same device and then uninstall one of them, the other application will crash. This is because the uninstaller also removes the MoSync server used for location services. Reinstall the required application and everything will be fine.
• For 2nd edition Symbian on Mac OS X the total length of your workspace path cannot be more than 32 characters.

Playing Sounds and Music

In many games and applications you will want to play a sound.  This may be backing music in a game, sound effects or alerts which require user input.  The MoSync SDK provides an audio API to help you do that.

Sound files can come from two places, either sounds you've packaged up with your application when you've distributed it, or they can be downloaded over the data network at runtime.  Either way, you need to create a resource which the API can recognise and pass to the operating system.

The 'Adding Resources to a Project' goes into a detail on how to add sound files to your project at build-time for packaging with your release.  In short, a sound file needs to be added as either a .media or a .umedia resource with a MIME type.

Due to limitations in the platform-provided API's there are a set of restrictions. Currently, it's not possible to play MP3 files on the Windows Mobile platform and the API only supports playing of one sound at a time.  If you want to make sure that all MoSync supported devices will be able to play your resources it is recommended that you use wav files.

.res MUSIC
.media "audio/mpeg", "music.mp3"

maSoundPlay(RES_SOUND);

maSoundStop();

if(maSoundIsPlaying())
maSoundStop();
maSoundPlay(RES_AUDIO, 0, maGetDataSize(RES_AUDIO));

int volume = maSoundGetVolume();

maSoundSetVolume(volume);

/**
 * @file PlayAudio.cpp
 *
 * This program shows how one can work with playing sounds and music.
 *
 * Todo: You need to add an audio resource file which you want to play.
 * In this example we have used Resource.lst file with following contents:
 * < .res RES_AUDIO
 *   .media "Audio/x-waf", "mobilesorcery2.wav"  >
 *
 * @Author Anders Malm
 */

#include <MAUtil/Moblet.h>
#include "MAHeaders.h"

using namespace MAUtil;

/*
 * Moblet class for playing music.
 */
class MyMoblet : public Moblet
{
public:
    MyMoblet();
    void keyPressEvent(int keyCode);
    void setVolume(int change);
};

/*
 * The constructor for Moblet class
 */
MyMoblet::MyMoblet()
{
    MAExtent e = maGetScrSize();
    maSetColor(0x0);
    maFillRect(0, 0, EXTENT_X(e), EXTENT_Y(e));
    maSetColor(0xffffff);
    maDrawText(0, 0, "Press 5 to Restart sound");
    maDrawText(0, 20, "Press 8 to Stop sound");
    maDrawText(0, 40, "Press 7 to Decrease volume ");
    maDrawText(0, 60, "Press 9 to Increase volume ");
    maDrawText(0, 80, "Press 0 to Exit");
    maUpdateScreen();

    // Panic message in case of failure.
    if(maSoundPlay(RES_AUDIO, 0, maGetDataSize(RES_AUDIO)) < 0)
        maPanic(0,"error playing sound!");
}

/*
 * For controlling music volume.
 */
void MyMoblet::setVolume(int change)
{
    int volume = maSoundGetVolume();
    volume += change;
    if(volume<0) volume = 0;
    else if(volume>100) volume = 100;

    maSoundSetVolume(volume);
}

/*
 * Key press events
 * Pressing key 0, Exits the program.
 * Pressing key 8, Stops playing sound.
 * Pressing key 5, Starts playing sound.
 * Pressing Keys 7 and 9, sets volume down and up respectively.
 */
void MyMoblet::keyPressEvent(int keyCode)
{
    switch(keyCode)
    {
        case MAK_0:
            maExit(0);
            break;
        case MAK_8:
            maSoundStop();
            break;
        case MAK_5:
            if(maSoundIsPlaying())
                maSoundStop();
            maSoundPlay(RES_AUDIO, 0, maGetDataSize(RES_AUDIO));
            break;
        case MAK_7:
            setVolume(-10);
            break;
        case MAK_9:
            setVolume(10);
            break;
    }
}

/**
 * Main execution of the program starts from here.
 */
extern "C" int MAMain()
{
    Moblet::run(new MyMoblet());
    return 0;
};

MoSound

This example application hows how to use MoSync's sound API. The example demonstrates how to play and loop a sound once.

This example is included in the MoSync SDK installation in the /examples folder. For information on importing the examples into your workspace, see Importing the Examples.

Behaviour

This application plays an mp3 file with the message "Mobile sorcery - making mobile magic".

Key Presses

• Press 0 or right-softkey to exit the application.

CameraDemo

CameraDemo is a simple application built with MoSync that demonstrates how to control a device's camera. It also uses the MoSync Widget API.

Main screen, Android	Main screen, iOS/iPhone	Settings screen, Android

This example is included in the MoSync SDK installation in the /examples folder. For information on importing the examples into your workspace, see Importing the Examples.

Behaviour

The application makes extensive use of the MoSync Widget API. It has three different screens:

• MainScreen is the default screen in the application form which the user can take snapshots, zoom in or out (if supported by the device), reach the other screens.

• SettingsScreen contains controls for configuring the camera and setting its properties. It also provides the ability to switch between cameras, where that is supported. This screen may differ from one device to another based on the available functionality on the device. 

• ImageScreen contains the latest captured image.

In the Code

The project is divided into several files. Each screen is implemented in a separate set of header and cpp files.

The main.cpp file is the main file of the project. It includes the code for creating MainScreen.

ImageScreen.cpp contains the code for creating and handling the ImageScreen, while  SettingScreen.cpp implements a class that creates and handles the SettingsScreen.

WidgetUtil.cpp contains simple wrappers for setting and getting properties of the widgets (similar to the files seen in our example application HelloNativeUI).

The .h header files contain the forward declarations for the code in the .cpp files.

Touch responses

• Tap buttons to capture image, switch screens, zoom in/out.

Controlling Cameras

In this tutorial we take a look at how to control a device's cameras through the MoSync Camera API. With the Camera API you can discover the number of cameras a device supports, set properties like zoom and image format, embed previews in your application, and, of course, take a picture. We also have an example application for you to look at, CameraDemo, that demonstrates some of the basic principles described here.

Camera API Syscalls

Here are the list of the syscall functions in the Camera API:

• maCameraNumber returns an integer indicating the number of available cameras on the device.
• maCameraSelect selects a camera associated with the index. The index is between zero and the number returned by maCameraNumber - 1. The default selected camera is the back-facing camera (0) which will be used if the user does not use this function. 
• maCameraSetPreview binds the selected camera to the widget specified by the handle. If called before calling maCameraSelect (for the first time) the default camera (back facing) will be bound to the preview.
• maCameraSetProperty adjusts the properties on the selected (or default) camera.
• maCameraGetProperty gets the assigned value for the specified property, or reads the values for read only properties.
• maCameraFormatNumber returns the number of available formats in the device.
• maCameraFormat stores a image size format in the list of user formats.
• maCameraSnapshot takes a picture and stores it in memory in the place reserved by a placeholder. To use this function with the default device's picture size, a user can pass -1 as the formatIndex.
• maCameraStart starts the live view on the preview widget. If no native preview is set, a fullscreen preview will automatically be initiated.
• maCameraStop stops the live view. When using the fullscreen default preview it will destroy that view and returns to the old view of the application.

General Usage

The recommended way of using the new Camera API is together with Widget API. To use the camera together with the Widget API follow these steps:
 
1. Get the number of available cameras on the device by calling maCameraNumber.
 
2. Add an instance of MAW_CAMERA_PREVIEW to your application with maWidgetCreate.
 
3. Set the widget parameters (only width and height are recommended).

4. Select one of the cameras by calling maCameraSelect:

maCameraSelect(MA_CAMERA_CONST_BACK_CAMERA);

5. Bind the preview and the camera by calling maCameraSetPreview so that the camera uses that preview for its live view.

void createCameraWidget ()
{
    mCameraPreview = maWidgetCreate(MAW_CAMERA_PREVIEW);
    widgetSetPropertyInt(
        mCameraPreview,
        MAW_WIDGET_WIDTH,
        MAW_CONSTANT_FILL_AVAILABLE_SPACE);               
    widgetSetPropertyInt(
        mCameraPreview,
        MAW_WIDGET_HEIGHT,
        MAW_CONSTANT_FILL_AVAILABLE_SPACE);
    //bind the widget to the default camera
    maCameraSetPreview(mCameraPreview);
    maWidgetAddChild( mMainLayoutWidget, mCameraPreview);
}

6. Check the available functionality on the device’s camera (zoom support, flash support, etc.) by calling maCameraGetProperty.

    char buffer[256];
    maCameraGetProperty(MA_CAMERA_FLASH_SUPPORTED, buffer, 256);

7. Start the camera by calling maCameraStart.

8. Change the properties as required by calling maCameraSetProperty.

9. Call maCameraSnapshot to take snapshots. Here You can see an example function that takes picture snapshots and stores them in a single place holder called mLastEnc.

void takeSnaphot()
{
if(mLastEnc != 0)
   maDestroyObject(mLastEnc);
mLastEnc = maCreatePlaceholder();
int res = maCameraSnapshot(mCurrentSizeIndex, mLastEnc);
if (res != MA_CAMERA_RES_OK)
    maPanic(res, "Failed to takeSnapshot");
}

10. Call maCameraStop to stop the camera when you are finished with it.

11. Destroy the Widget if required.

Camera Properties

Camera properties can be set and read through the maCameraSetProperty and maCameraGetProperty functions:

Read/Write:

• MA_CAMERA_FLASH_MODE -- Sets the mode of flash for the camera (auto, infinity, macros, fixed).

• MA_CAMERA_FOCUS_MODE -- Sets the mode of focusing for the camera (auto, infinity, macros, fixed).
• MA_CAMERA_IMAGE_FORMAT -- Sets the image format (MA_CAMERA_IMAGE_JPEG, MA_CAMERA_IMAGE_RAW).
• MA_CAMERA_ZOOM -- Sets the zoom level (zero to MA_CAMERA_MAX_ZOOM).

Read Only:

• MA_CAMERA_ZOOM -- The maximum zoom supported by the device.
• MA_CAMERA_ZOOM_SUPPORTED -- True if the device supports zoom.
• MA_CAMERA_FLASH_SUPPORTED -- True if the device supports flash.

For more details about these functions, see the MoSync API Reference Manual.

Implementation

Known Issues and Limitations

The Camera API for the MoSync Android runtime currently uses Android 2.2 (API Level 8) which only supports one camera.

Collections in MoSync

The MoSync SDK provides several different collection objects, suitable for different occasions.  Collections let you deal with sets of object collectively, but the way you access the collection varies.  

Collections are not implemented consistently in MoSync though, so different collection types are not as interchangable as you might expect.

Collection Memory Usage

Typically, collections will be created on the stack rather than the heap.  This will mean that if you have a collection of object pointers (the objects themselves will be in the heap), and the collection goes out of scope, you may loose the pointers to the objects in the heap and you won't be able to access them.  The objects will still exist though, and you've got a memory leak.  Keep close track of collections, and ensure that they are in a suitable scope.  Object scope is very commonly used.

class MyClass
{
public:
    MyClass();
    virtual ~MyClass();
private:
    Vector<MyObject*> myVector;
};

In the above example, the Vector of MyObject pointers will be created when the object is created, and destroyed when the object is destroyed.  The objects the pointer point to will not be destroyed unless you specifically destroy them.  You can do this in the class destructor if you do not wish to refer to those objects again.

MyClass::~MyClass()
{
    //Destroy the objects in my Vector
    Vector_each(MyObject*, itr, myVector) {
        delete *itr; //Delete the object
    }
}

Always be aware of the lifespan of objects in collections, and delete the objects as necessary.

Iteration

In most collections, there are ways to iterate through the contents.  These are specific to the collection type, and methods for iteration are described with each collection type.  They are not consistent, so don't assume that because you can use one method for iterating one type of collection it will be exactly the same for another.

In C++ there isn't an iteration interface, nor is there a keyword for iteration.  For example, in C# there is the IEnumerable interface and the foreach keyword which lets you iterate through any collection:

foreach(String in myStringCollection)
{
}

This isn't supported in C++, so iteration is slightly more verbose.

Arrays

Arrays and Vectors are the simplest collections in MoSync.  They provide easy access to stored objects and data, and can be returned by functions and methods.

The simplest collection type is an array.  This is supported in C and C++ rather than being a collection supported in MoSync specifically.  It provides random access (that is, you can access any item in the collection), but it stores its contents sequentially in memory.  This can cause problems if you are storing a lot of large objects, as the contiguous memory may not be available.

You can create an array by using the [] operators.  Arrays can be of any object or primitive type.  You must specify the size of the array when you create it and arrays cannot be easily resized, nor can items be easily inserted into them.  They are small, require no additional overhead and are fast.  This code will create an array of twenty chars.

char myCharArray[20];

Any item in the array can be accessed by its zero-based index number.

char thirdChar = myCharArray[2]; // Zero-based

Values can be written as well

myCharArray[2] = 'c';

When you have finished with an array, you will need to use the delete [] instruction, and not delete.

delete [] myCharArray;

Which will then delete every item in the array.

Typically in arrays (and most collections), you'll store a primitive value (char, int, byte et cetera), or an object pointer.  You can store objects in the array directly, but enough contiguous memory must be available.  

To iterate through an array, you access the array with the [] operator sequentially.  You do need to know the size of the array before you start, but you need to know that to create it.  For example

for(int i = 0; i < 20; i++)
{
   printf("%c", myCharArray[i]);
}

Vectors

Vectors are part of the MAUtil namespace.  To use them, you will need to include MAUtil/Vector.h. 

#include <MAUtil/Vector.h>
using namespace MAUtil;

A vector is an object wrapper around an array.  All the storage will be done in the array, but the vector will let you iterate through the collection, insert items into the collection and resize the collection.

Vectors are similar to C# and Java List<> collections.  MoSync List<> collections are not. 
See below for details of MoSync List<>.

You don't need to specify a size when you create a vector.

Vector<MyObject*> myVector;

What you do need to specify is the type of data you are going to store, by adding the type name between the angle brackets.  Once you specify this, you can only add items of that type.  In the above instance, these are MyObject pointers. You can only add MyObject pointers to this vector, and not MyObjects themselves or pointers of a different class.

You can add items into the vector using the .add() method.

myVector.add(new MyObject());

You can also insert items at a specific point. 

myVector.insert(2, new MyObject());

Existing items will be moved down the underlying array.  This is a comparitvely expensive operation, so only do it if the order is important.

Vectors maintain the order in which you add items.  If you iterate through the vector, you
will find objects in the same order you added or inserted them.

Individual items can be removed from vectors using the remove() method. There are three different ways you can remove items from a vector.

myVector.remove(MyObject**); 

This is a pointer to a MyObject pointer.  We'll look at iterators shortly, but MyObject** will probably be an iterator.

myVector.remove(1);

Removes the second item from the zero-based index.

myVector.remove(1, 3);

To completely empty a vector, you can use the clear() method.

Removes the second, third and fourth items from the vector.  Remember, this does not delete any objects if your vector contains pointers.  It only removes the pointers.  If you want to delete the object you must still use delete.

The vector starts with a small array of the type you've specified.  By default it will create an array of the type containing four items.  If you add a fifth, then the a new array is created, and all the items are copied across.  The new array will be twice the size of the old array.  If you exceed the reserved space, then the array will be recreated and the data carried across again.  The obviously adds overhead.  If you know that you want 20 items, then create it with space for 20 items.  You can do this in three ways.

Firstly, you can set the size in the constructor.  As Vectors are normally created on the stack, then there is no opportunity to use the new instruction.  Instead, in C++ you can specify it when your object is created.  In your header file (.h) you can have something like this:

class MyClass
{
public:
    MyClass();
    virtual ~MyClass();
private:
    Vector<MyObject*> myVector;
};

And in the code file (.cpp) you can specify the size of the vector in the constructor.

#include "MyClass.h"

MyClass::MyClass() : myVector(20)
{
}

This will initialise the vector with a size of 20.  There are also two methods for sizing the vector, resize() and reserve().  Both will set the size of the underlying array, but resize() will move the current cursor to the end of the array.  This means that if you resize(20) and then .add(new MyObject()) then the vector will have 21 items in it and have a capacity of 40.  In general, use reserve() when you want to allocate memory.  You cannot resize() or reserve() to a size smaller than you are currently using.

You can get the current usage by using the size() and capacity() methods.  If you want to know how many items are in a vector, use size().  To find out how many it can take, use capacity().  To easily find if the vector is empty, use the empty() method.

if(myVector.empty())
{
    // Do something.
}

Vectors, like arrays, are random access.  You can access any item in the vector using [].

MyObject* myObject = myVector[3];

You can also get direct access to the array using the pointer() method.

To iterate a vector, you use a vector iterator.  These are pointers to each item in the vector, and are of the type Vector<Type>::iterator.  For example

Vector<MyObject*>::iterator

You can get iterators to the first object, and to the point beyond the last object using the begin() and end() methods.  Because the underlying array is in contiguous memory, then the iterators are sequential.  The iterator is really a pointer to the type of the object (or value) stored.  In our example, the iterator will be of a type MyObject**.  It is a pointer to a MyObject pointer.

We can use the iterators from begin() and end() to test our iteration.

for(Vector<MyObject*>::iterator itr = myVector.begin(); 
itr != myVector.end(); 
itr++)
{
    // Do something.
}

This will then give us a MyObject** for each loop, called itr.  You can use the object stored as normal if you dereference it.

MyObject* currentObject;
for(Vector<MyObject*>::iterator itr = myVector.begin(); 
itr != myVector.end(); 
itr++)
{
    currentObject = *itr; // Dereference it.
    currentObject->method();
}

There is also a macro you can use a short cut for iterating vectors.  Vectors are now the only collection to have such a macro.

Vector_each(Type, iterator variable, vector);

For instance, instead of the long for statement earlier, we can have the more readable

Vector_each(MyObject*, itr, myVector)
{
    // Do something.
}

If you change the vector during an iterative process, the iterator may become invalid, 
with undefined consequences.  Don't add or remove items from a vector whilst you are 
iterating through it.

Lists

Lists are part of the MAUtil namespace.  To use them, you will need to include MAUtil/List.h.

#include <MAUtil/List.h>
using namespace MAUtil;

If you come from a Java or C# background, List will not behave as you expect.  The MoSync equivalent of a Java/C# List is Vector<>.  In MoSync Lists are doubly-linked lists.

MoSync lists allow you to create a collection of items, where each item knows which is the item before it and after it in the list.  This has a big impact on how you iterate through a list.

As there isn't an underlying array, then you don't need to specify the size of your collection, nor is there an impact on performance for inserting an item in the list.  Each object or value you store will be wrapped in a very light object, so there is a very small memory overhead, but its flexibility is superb.

The downside of this is that there isn't any method of random access.  You have to navigate the list serially, although you can go backwards and forwards through the list.

You create the list in a similar way to the vector.

List<MyObject*> myList;

You can then add items very easily to either the beginning or the end of the list by using addFirst() and addLast() respectively.

You can only add items into the middle of the list, or remove items from the if you've got an iterator.

You can get an iterator in the same way as you can with a vector, using the begin() and end() methods.  You can then access the objects and values stored using the prev() and next() methods.  You can test to see if you are at the start or end of a list using the hasPrev() and hasNext() methods.

The iterators for lists are of the type List<type>::ListIterator and List<type>::ConstListIterator.  Note the capitalisation of Iterator for this iterator.

List<MyObject*>::ListIterator itr = myList.begin();
MyObject* currentObject;
while(itr.hasNext())
{
    currentObject = itr.next();
}

Note that you don't increment the iterator like you do with vectors.  The next() and prev() methods return the value stored and increment the iterator.

You can insert items into list without much of a perform hit as there is no array to reallocate.  You do have to do this from an iterator though.

itr = myList.begin();
while(itr.hasNext())
{
    if(itr.next() == 1)
    {
        // Add the value 2 after this item.
        myList.insert(itr, 2);
    }
}

Equally, remove is done through the iterator.  When you add an item using insert it is placed after current iterator.  When you remove() an item, it removes the item from the current position.  ListIterators are not corrupted if you alter the collection, unlike vectors.  Remember, if you remove a pointer to an object, you are not destroying the object itself.  You still need to call delete.

The code below shows creating and altering a List<int>.

#include <MAUtil/Moblet.h>
#include <conprint.h>
#include <MAUtil/List.h>

using namespace MAUtil;

class MyMoblet : public Moblet 
{
public:
    List<int> myList;

    MyMoblet() 
    {
        // Create a list with an item missing.
        myList.addFirst(0);
        myList.addLast(1);
        myList.addLast(3);

        // Show the original list
        showList();

        // Now add 2 into the list
        List<int>::ListIterator itr = myList.begin();

        itr = myList.begin();
        while(itr.hasNext())
        {
            if(itr.next() == 1)
            {
                // Add the value 2 after this item
                myList.insert(itr, 2);
                lprintfln("Added 2");
            }
        }

        // Now show the list again
        showList();

        // Now remove 1 from the list
        itr = myList.begin();
        while(itr.hasNext())
        {
            if(itr.next() == 1)
            {
                // Remove this item
                myList.remove(itr);
                lprintfln("Removed 1");
            }
        }

        // Now show the list again
        showList();
    }

    void keyPressEvent(int keyCode, int nativeCode) 
    {
        this->close();
    }

    void showList()
    {
        lprintfln("I've got %d items", myList.size());
        List<int>::ListIterator itr = myList.begin();
        while(itr.hasNext())
        {
            lprintfln("Next value : %d", itr.next());
        }
    }
};

extern "C" int MAMain()
{
    Moblet::run(new MyMoblet());
    return 0;
}

Stack

There are two conceptually related, but utterly separate collections in MoSync - Stack and Queue.  They both are designed for serial access to collections where the order of the collection is vital.

Stacks are part of the MAUtil namespace.  To use them, you will need to include MAUtil/Stack.h.

#include <MAUtil/Stack.h>
using namespace MAUtil;

The Stack collection (capitalised to show that we don't mean the stack program memory, but a Stack<> collection), is a vector, but where you can only access the most recently added item.  You can put as many items as you want onto the Stack, but you can only get the latest item.  If you imagine a stack of books, you can see that it is only the book at the top which is accessible.  This kind of collection is also called first-in-last-out or very occasionally, FILO. 

You create a Stack like you would a vector

Stack<MyObject*> myStack;

Unlike vectors though, you cannot specify a size in advance.  It uses the vector's default initial size of 4, and will resize itself when it needs to.

When you want to add an item on a Stack, you are said to push it onto the Stack.  The method for adding to a stack is then

myStack.push(new MyObject());

When you want to remove an item from the stack, you are said to pop it off the Stack.

myStack.pop();

Remember, if you have a collection of object pointers, popping an item off the stack will not destroy the object.  You have to call delete yourself.

To get access to the next item on the Stack using the method peek().

MyObject* nextObject = myStack.peek();

You can test the size of the Stack using size() although you cannot test its capacity.  You can also see if it has no items in it using empty().  You can remove all the items from the stack at once using clear().

There are no iterators in the stack.  If you want to find an item, you have to keep popping items off the top until you get the one you want.  If you want to remove an item from the middle, you need to copy the data to another Stack.

As you'll see from the example below, iterating Stacks is laborious.  They are best suited to times when the order is important.  They are frequently used to allow users to retrace their steps.  For instance, you can keep track of the order the user navigated the screens in your application.  When the users wants to go back one screen, then you can pop the last value off your stack.

#include <MAUtil/Moblet.h>
#include <conprint.h>
#include <MAUtil/Stack.h>

using namespace MAUtil;

class MyMoblet : public Moblet 
{
public:
    Stack<int> myStack;

    MyMoblet()
    {
        // Create a list with an item missing.
        myStack.push(3);
        myStack.push(1);
        myStack.push(0);

        // Show the original stack
        showStack();

        // Now add 2 into the stack
        // We need another stack to copy removed items to.
        Stack<int> tempStack;
        while(myStack.peek() != 1)
        {
            // Copy the top of the stack to another stack.  Remember that the new stack will
            // have everything in reverse order
            tempStack.push(myStack.peek());
            myStack.pop();
        }
        
        // Add the value 2
        myStack.push(2);

        // Now copy everything back again
        while(tempStack.size() > 0)
        {
            myStack.push(tempStack.peek());
            tempStack.pop();
        }

        // Now show the Stack again
        showStack();

        // Now remove 1 from the stack
        while(myStack.peek() != 1)
        {
            // Copy the top of the stack to another stack.  Remember that the new stack will
            // have everything in reverse order
            tempStack.push(myStack.peek());
            myStack.pop();
        }
        
        // The item at the top is 1.  Remove it
        myStack.pop();

        // Now copy everything back again
        while(tempStack.size() > 0)
        {
            myStack.push(tempStack.peek());
            tempStack.pop();
        }

        // Now show the Stack again.
        showStack();
    }

    void keyPressEvent(int keyCode, int nativeCode) 
    {
        this->close();
    }

    void showStack()
    {
        lprintfln("I've got %d items", myStack.size());
        // We need to copy the Stack to another stack whilst we go through it.
        Stack<int> tempStack;
        while(myStack.size() > 0)
        {
            lprintfln("Next value : %d", myStack.peek());
            tempStack.push(myStack.peek());
            myStack.pop();
        }

        // OK, we've shown them all, now we need to put myStack back together.
        while(tempStack.size() > 0)
        {
            myStack.push(tempStack.peek());
            tempStack.pop();
        }
    }
};

extern "C" int MAMain()
{
    Moblet::run(new MyMoblet());
    return 0;
}

Queues

Queues are part of the MAP namespace.  To use them, you will need to include MAP/Queue.h, and ensure that you've got MAP.lib included as a library in your project settings.  Alternatively, copy the file Queue.h out of the includes directory and include it directly in your project, although if you do this, you will need to replace newobject() with new and deleteobject() with delete, or alternatively, implement the MemoryMgr class as well.

#include <MAP/Queue.h>
using namespace MAP;

Queues are logically very similar to Stacks, but the implementation is quite different.  Differences in implementation will be highlighted as the collection is described.  

Logically, a queue is the same as a Stack, with the exception that the first item is the only one available, not the last item.  This is sometimes called first-in-first-out or very occasionally FIFO.

To create a queue, it is almost the same as stack

Queue<MyObject> myQueue;

The important difference to note is the data type you provide it.  MoSync queues only contain pointers.  You provide it with the type of data pointer you want.  The above code will create a Queue of MyObject pointers, and not MyObject, despite what it looks like.  If you had the code

Queue<MyObject*> myQueue;

You would get a queue of MyObject**.  Equally then

Queue<int> myQueue;

Will create a queue of int* and not int.

When you add an item to a queue, this is called enqueueing, and the method is enqueue().  To remove a method, you dequeue() it.  Whereas with the Stack, when you peek() at a value it leaves it on the Stack and have to pop() it off, dequeue() will remove it from the collection.  It is the responsibility of the code calling dequeue()  to delete the object after use if necessary to prevent memory leaks.

myQueue.enqueue(new MyObject());
MyObject* currentObject = myQueue.dequeue();

Whilst Queues were not designed for random access, there are methods in the MoSync implementation for accessing values at will.  There aren't any iterators with queues however.

You can read values using peekAt() method, providing the method with the index number of the value you want, or peek() which will return the next item, although these will leave the item in the queue. 

You can also find the location in the queue of a specific object.  The find() method will return an items index number.  

Like vectors, you can set capacity of the queue, and it has an array internally for storage.  Unlike a vector, you cannot resize a queue, so when it is full, then that's it.  Your item will not be added, no return value will be given by enqueue() and no error will be raised, so it is important to check the amount of space left in the queue using getCapacity() (not capacity() like in vector) and getCount() (not size()).

You can remove all the items in the queue (but not delete the objects) using clear().

Queues are useful for marshalling activities.  For instance, if you've got a long list of items which need to be downloaded, rather than creating an instance of Downloader for each of them, you can have one Downloader and a queue.  You can create a class which gets the next URL from the queue and downloads the data.  Once it is complete, it can check the queue again for the next request.

Dictionary-based collections

There are some collections in MoSync which are a little more powerful, allowing you to access their contents through you own index.  The basis for these is the Dictionary.  Whilst you never create a Dictionary on its own, only classes derived from Dictionary they have a common syntax.  

Dictionaries are collections of Pairs (you may know these also as Key/Value pairs).  Each pair has a key with which you can reference your value.  Often, you don't need to know about the pairs in the collection, but if you iterate through a Dictionary, then your iterator will be a pair.

To create a Dictionary, you need to create one of the derived classes, Map, HashMap or Set.  They all follow the same pattern

Map<Key Type, Value Type> myMap;
HashMap<Key Type, Value Type> myHashMap;
Set<Key Type, Value Type> mySet;

For example, you can create a collection of the names of your friends and their phone numbers.  Both their names and numbers will be stored as strings.  The names will be the key and the phone number the value.

Map<String, String> myFriends;

You can then add items to the collection.

myFriends.insert("Rupert Bear", "Norwood 1212");

The insert() method actually returns another Pair, this time with a Dictionary::Iterator and a boolean value.  The iterator points to the value you've just added, and the boolean contains true if the insert was successful.

Note, unlike Vectors, there is no add method, because Dictionaries don't keep the same 
concepts of ordering.

Dictionary classes are all random-access, you can have access to any item at any time.  We can find Rupert's phone number at any time.  The find method returns a Pair<String, String>.  The Pair has two properties for the key and value.  Rather than being called key and value, they are called first and second.  The key is in first, and the value is in second.

String& rupertsNumber = myFriends.find("Rupert Bear")->second;

Map and HashMap also provide support for [] operators.  This doesn't return the Pair but just the value.

String& rupertsNumber = myFriends["Rupert Bear"];

myFriends.erase("Rupert Bear");

is valid.  Note that the method is erase() and not remove()  as it is on vectors and lists.

So, Dictionaries are power collections we can use very flexibly to store data.  There are some differences between the three collections.

Map

The Map is the simplest of the Dictionary classes.  It is a simple mapping between the key and the value.  For a given key, it will return the location of the value.  It achieves this by comparing the key provided with its list of keys.  It checks each one, and when it finds a match it will return the value.  For this reason, Map is most suitable when the collection is small.  With a very large collection, any search operation may have to compare every key in its collection until it finds the correct value. The elements in Map are sorted from lower to higher key values.

HashMap

The HashMap converts the key you provide using a hash function.  It then assigns the value into a location in memory depending on the value of the hash.  This is important, as it can calculate this hash again when you want to retrieve the value.  This means that it doesn't have to compare all of the keys looking for the value you want.  It does mean that it does a little more work than a Map, but it is much more suitable for larger collections, e.g. collections which are likely to have more than five entries. 

Set

The Set is like a map, except that values are unique as well as keys.  As the values are unique, then the storage is in the order of the values, and not the keys.  This means that it is unlikely that when you iterate through a collection, that the values are in the same order as they were entered in.  Sets are essential when having unique keys and unique values is essential.  Set does not support the [] operator, so you have to use the .find() method to retrieve values.  The keys in a Set are not hashed.

Iteration

Dictionary Iterators cannot be unassigned, which makes iterating through Dictionaries quite verbose.  There also isn't a handy macro like there is for vector.  You have to either already have an Iterator or create one in the for statement.

for(Map<String, String>::Iterator itr = myFriends.begin();
itr != myFriends.end(); 
itr++)
{
       // Do something.
}

To create an iterator, you need to type it exactly as the Dictionary is typed, so if you've got

Map<String, String> myFriends;

Then the Iterator has a type of

Map<String, String>::Iterator

As described above, Iterators provide access to Pairs.  You need to use the first and second properties on them for the key and value respectively.

for(Map<String, String>::Iterator itr = myFriends.begin();
itr != myFriends.end();
itr++)
{
   lprintfln("Friend: %s Number: %s", itr->first.c_str(), itr->second.c_str());
}

Below is code to create an manipulate a HashMap<String, String>.  You will see how the order changes.

#include <MAUtil/Moblet.h>
#include <conprint.h>
#include <MAUtil/HashMap.h>
#include <MAUtil/String.h>

using namespace MAUtil;

class MyMoblet : public Moblet 
{
public:
    HashMap<String, String> myFriends;

    MyMoblet() 
    {
        // Add some friends
        myFriends.insert("Rupert Bear", "Norwood 1212");
        myFriends.insert("Noddy", "Playtown 2020");
        myFriends.insert("Windy Miller", "Trumpton 2323");

        // Show the original dictionary
        showDictionary();

        // Find a friend
        String friendsNumber;
        friendsNumber = myFriends.find("Rupert Bear")->second;
        lprintfln("Rupert's number is %s", friendsNumber.c_str());

        // Erase a friend
        myFriends.erase("Noddy");

        // Show the new dictionary
        showDictionary();

        // Find a friend by iterator
        HashMap<String, String>::Iterator myFriend = myFriends.begin();
        lprintfln("My first friend is %s whose number is %s", 
        myFriend->first.c_str(), myFriend->second.c_str());
    }

    void keyPressEvent(int keyCode, int nativeCode) 
    {
        this->close();
    }

    void showDictionary()
    {
        lprintfln("I've got %d items", myFriends.size());
        for(HashMap<String, String>::Iterator itr = myFriends.begin(); 
        itr != myFriends.end();
        itr++)
        {
            lprintfln("Friend: %s Number: %s", itr->first.c_str(), 
            itr->second.c_str());
        }
    }
};

/*
* Main program starts here.
*/
extern "C" int MAMain()
{
    Moblet::run(new MyMoblet());
    return 0;
};

Using MAUtil Set, Map, HashMap

The MAUtil classes Set, Map and HashMap provide generic containers similar to std::set, map and unordered_map in the STL or Java's Set, Map and Hashtable. They provide many of the same familiar operations. Here we describe examples for Set, Map, and HashMap:

Set

/**
 * @file Set.cpp
 * @author Naveed Asif
 *
 * Description:
 *
 *  In this tutorial we will learn the use of Set
 *  container. Initially a list of numbers is
 *  created and then the difference between erase()
 *  clear() is shown.
 */

#include <MAUtil/Moblet.h>
#include <conprint.h>
#include <MAUtil/Set.h>

using namespace MAUtil;

class MyMoblet : public Moblet
{
public:
	// Set is declared.
	Set<int> myNumbers;

	MyMoblet()
	{
		// Add some numbers.
		myNumbers.insert(786);
		myNumbers.insert(111);
		myNumbers.insert(222);
		myNumbers.insert(333);

		// Shows the original dictionary in the console.
		// Note: The dictionary values will be displayed in
		// ascending order.
		showDictionary();

		// Locates and Erases any specific Number.
		myNumbers.erase(333);

		// Look at the dictionary and notice that 333 is erased.
		showDictionary();

		// This will delete all the members of container.
		myNumbers.clear();

		// Will show that you got 0 members.
		showDictionary();
	}

	/**
	 * Called when a key is pressed on the keypad.
	 */
	void keyPressEvent(int keyCode, int nativeCode)
	{
		if (MAK_BACK == keyCode || MAK_0 == keyCode)
		{
			close();
		}
	}

	/**
	 * showDictionary function is used to display all the
	 * members in myNumbers container.
	 */
	void showDictionary()
	{
		printf("I've got %d Numbers", myNumbers.size());
		if (myNumbers.size() > 0)
		{
			printf("Numbers are:");
		}
		for(Set<int>::Iterator iter = myNumbers.begin();
			iter != myNumbers.end();
			iter++)
		{
			printf("%d", *iter);
		}
	}
};

/*
 * Main function where the program starts
 */
extern "C" int MAMain()
{
    Moblet::run(new MyMoblet());
    return 0;
}

/**
 * @file Map.cpp
 * @author Naveed Asif
 *
 * Description:
 *
 *  In this tutorial we will learn the use of Map
 *  data structure. Initially a list of friends is
 *  created and then the Iterator's methods begin(),
 *  erase(), and find() are used.
 */

#include <MAUtil/Moblet.h>
#include <conprint.h>
#include <MAUtil/Map.h>
#include <MAUtil/String.h>

using namespace MAUtil;

class MyFriend
{
private:
	String myName;
	String myAddress;

public:
	MyFriend(String name, String address)
	{
		myName = name;
		myAddress = address;
	}

	void show()
	{
		printf("%s, %s", myName.c_str(), myAddress.c_str());
	}
};

class MyMoblet : public Moblet
{
public:
	// Map is declared.
	Map<String, MyFriend*> myFriends;

	MyMoblet()
	{
		// Add some friends.
		addFriend("Rupert Bear", "Norwood, England");
		addFriend("Ghuman", "Stockholm, Sweden");
		addFriend("Windy Miller", "Trumpton 2323");

		// Shows the original dictionary in the console.
		// Note: The dictionary values will be displayed in
		// ascending order.
		showDictionary();

		// Finds a friend using the find method and displays it
		// in the console.
		printf("--------------");
		printf("Found friend:");
		MyFriend* myFriend = myFriends.find("Rupert Bear")->second;
		myFriend->show();

		// Locates and erases a friend.
		myFriends.erase("Ghuman");

		// Look at the dictionary and notice that "Ghuman" is erased.
		showDictionary();

		// Finds the first entered friend.
		printf("--------------");
		printf("My first friend is:");
		Map<String, MyFriend*>::Iterator iter = myFriends.begin();
		iter->second->show();
	}

	/**
	 * Add a new friend to the dictionary.
	 */
	void addFriend(String name, String address)
	{
		myFriends.insert(name, new MyFriend(name, address));
	}

	/**
	 * Called when a key is pressed on the keypad.
	 */
	void keyPressEvent(int keyCode, int nativeCode)
	{
		if (MAK_BACK == keyCode || MAK_0 == keyCode)
		{
			close();
		}
	}

	/**
	 * showDictionary function is used to display all the
	 * pair values in myFriends Map function
	 */
	void showDictionary()
	{
		printf("--------------");
		printf("I've got %d friends:", myFriends.size());
		for(Map<String, MyFriend*>::Iterator iter = myFriends.begin();
			iter != myFriends.end();
			iter++)
		{
			iter->second->show();
		}
	}
};

/*
 * Main function where the program starts
 */
extern "C" int MAMain()
{
    Moblet::run(new MyMoblet());
    return 0;
}

All the classes have reference documentation. Also, the source code is available in $MOSYNCDIR/include/MAUtil/ in your MoSync package.

Using MAUtil Vector

The MAUtil::Vector class provides a generic, dynamically resizeable container similar to std::vector in the STL, Java's Vector or a .NET List. It provides many of the same familiar operations. 

Starting with Vectors

A Vector can be used as a generic collection, allowing you to grow the set whilst maintain the order in which items were added.  Vectors add items as their value type.  When you add or insert an item on the list, it adds the value or object to that list.  If you have a Vector of a complex object type, it will add that object to the list, and not a pointer to it, unless you explicitly request it.

For example

Vector<UserDetail> mUserDetails;

Will create a Vector of UserDetail objects, and not a Vector of UserDetail*.  Not all collections in MoSync behave in this manner.  To create a Vector of pointers to UserDetails objects, use

Vector<UserDetail*> mUserDetails;

Vectors are generic collections, so you define the type of object you want to store when you define the Vector.  The snippet below demonstrate creating Vector of int on the stack.

Vector<int> mInts;

Vectors store their items in contiguous memory.  Internally, there is an array which is used for storage with the Vector class maintaining the order.  Collections, including Vector, can cause you to run into memory allocation (malloc) errors if there isn't enough free contiguous memory left.  Broadly speaking, if you are storing a complex object type like the UserDetail object in the example above, you are always better off storing pointers than the values.  If you are using primitive types (int, byte), then store the values.

Adding items to a Vector

There are two ways you can add new items into a Vector, the add() and the insert().  The method add() appends the new item at the end of the list.

mInts.add(5);

You can also insert an item into the Vector at a requested position using the method insert().

mInts.insert(2, 100);

Where the first parameter is the index number you wish to insert the number (on a zero-based index) and the second is the value you wish to store.  All subsequent entries are moved along.  This has the potential to be very slow on large collections, so try to sort items before you enter them into the Vector. 

As the Vector is based on an array, you can still access the items using the [] operators.  You can use the index number to change the value of an item in an array.  This won't cause objects to be deleted, so if you are storing pointers to objects, then you will need to delete the item to prevent a memory leak.

UserDetails* mNewUser;
Vector<UserDetails*> mUserDetails;
...
// Overwrite the first entry.
UserDetails* temp = mUserDetails[0];
mUserDetails[0] = mNewUser;
delete temp; // Delete the old entry

Removing Items from a Vector

You can remove an item from a Vector using the remove() method.  There are two ways this can be called.  Firstly, you can request for a specific index number to be removed, but you can also remove with an iterator.  There is more about iterators below.

mUserDetails.remove(0);

Again, removing items from the Vector won't delete them from memory if they are pointers to objects.  You need to delete them explicitly or you will have a memory leak.

UserDetails* temp = mUserDetails[0];
mUserDetails.remove(0);
delete temp;

Removing items from the end of the list is very quick, but if you remove from the middle (or the start) of the list, then the other items need to be reordered, which can be slow.

Iterating through Vectors

You can work you're way through all the items in a Vector in two different ways.  As the Vector is based on an array, you can iterate through the items by index number 

Vector<int> numbers;
.... 
 // iterate through the vector using the 
// [] operator, printing each element.
for(int i = 0; i < numbers.size(); i++) {
    printf("numbers[i]: %d", numbers[i]);
}

A second method is to use the iterator.  Iterators are pointers to the items in the Vector, but are of a type

Vector<T>::iterator

Note that with Vectors the iterator has a low-case 'i' whilst in other collections (Set for example) the iterator has an upper-case 'I'.

Vector<int> numbers;
for(Vector<int>::iterator i = numbers.begin(); i < numbers.end(); i++)
{
  printf("%d", *i);
}

You can use the iterator to step through items in the Vector using the iterators returned by the methods begin() and end().  Also note that the iterator is a pointer to the value, so you will have to dereference it with an *.

Finally, there is a macro to make iteration more readable.  You can use the macro Vector_each to iterate the Vector. 

Vector_each(int, i, numbers)
{
    // The iterator needs to be dereferenced.
    printf("numbers[i]: %d", *i);
}

Vector_each takes three arguments; the type stored by the Vector, the variable name you want to refer to the iterator and finally the Vector itself.

Size and Capacity

There's an important distinction between the size and capacity of a Vector. Vectors grow dynamically to accomodate additional elements that are added to them. When an element is added, exceeding the current capacity, the capacity is doubled. However, the size only increases by one. This snippet demonstrates the behaviour:

for(int i = 0; i < 10; i++)
{
    numbers.add(i);
    printf("Size: %d  Capacity: %d", numbers.size(), numbers.capacity());
}

The output looks like this:

  Size: 1 Capacity: 4
  Size: 2 Capacity: 4
  Size: 3 Capacity: 4
  Size: 4 Capacity: 8
  Size: 5 Capacity: 8 
  Size: 6 Capacity: 8
  Size: 7 Capacity: 8
  Size: 8 Capacity: 16
  Size: 9 Capacity: 16
  Size: 10 Capacity: 16

In this case, the memory used to store the Vector elements is reallocated twice, each time requiring all the elements to be copied to the newly allocated memory location.

It is possible to reserve() a certain capacity, which is useful in cases when the number of elements to add is known beforehand (but not at compile time) in order to avoid superfluous reallocations:

numbers.reserve(11);
for(int i = 0; i < 10; i++)
{
    numbers.add(i);
    printf("Size: %d  Capacity: %d", numbers.size(), numbers.capacity());
}

The output looks like this:

  Size: 1 Capacity: 11
  Size: 2 Capacity: 11
  Size: 3 Capacity: 11
  Size: 4 Capacity: 11
  Size: 5 Capacity: 11 
  Size: 6 Capacity: 11
  Size: 7 Capacity: 11
  Size: 8 Capacity: 11
  Size: 9 Capacity: 11
  Size: 10 Capacity: 11

Note
Most functions that somehow manipulate the size of the vector do not affect the capacity if the new size is smaller than the previous. Do not assume that resize(0) will free up memory if the Vector previously contained thousands of elements.

Internal Storage

HTTP Connections

This tutorial will show you the basics of HTTP connections in MoSync. You will see how easy it is to write applications which can access HTTP-based information. You will also see how easy it is to stream information over HTTP. This example is written from a Moblet template.

Initializing

#include <mautil/connection.h> 
 #include <mastdlib.h> 
 #include <conprint.h> 
 #define CONNECTION_BUFFER_SIZE 1024 

connection.h is included to provide the basic connection functionallity.
mastlib.h is included to add the atoi function which converts the contents of an array to an int.
conprint.h adds the printf function which writes text to the screen as a simple console.
CONNECTION_BUFFER_SIZE defines the size of the buffer in which data is collected.

 class MyMoblet : public MAUtil::Moblet, private MAUtil::HttpConnectionListener 

To provide the functionallity we inherit function declarations from the HttpConnectionListener class.

  void httpFinished(MAUtil::HttpConnection *conn, int result); 
  void connRecvFinished(MAUtil::Connection *conn, int result); 
  void connReadFinished(MAUtil::Connection *conn, int result); 

The httpFinished function is a callback which is called whenever a http connection is initiated and we can recieve a response. When we use the recv function for the http connection connRecvFinished is called everytime a new chunk of data is recieved. If we use the read function instead, the connReadFinished function will be called when the read is done. More about these functions later in this tutorial.

  char mBuffer[CONNECTION_BUFFER_SIZE]; 
  MAUtil::HttpConnection mHttp; 

mHttp is a MAUtil::HttpConnection object which represents the actual connection. Each one of these may only handle one connection at the time so to enable multiple connections we need to define multiple HttpConnection objects. Always make sure that a connection is closed before connecting to it again.

 MyMoblet::MyMoblet() : mHttp(this) 

The constructor sets itself as the listener for the HttpConnection object so that the callbacks declared in MyMoblet will be used.

  InitConsole(); 
  gConsoleLogging = 1; 

In our entry point, MAMain we initialize the console and enable logging. This means that everything that everything that we send to the console is also logged in a log file. If you handle large amount of data and would want to output information to verify behaviours of your application this will help you. This file is located in the Output folder of your project and is called log.txt.

Connections and Responses

Too initiate an http connection we call the create function of the HttpConnection object. All you need to provide is the url and if you need to use GET or POST. In this example we send a POST request to a server.

  int res = mHttp.create(url, HTTP_POST); 
  if(res < 0) { 
  printf("unable to connect - %i\n", res); 
  } else { 
  mHttp.finish(); 
  mIsConnected = true; 
  } 

If the create function returns a value below zero this means that it have failed for some reason. Please check the API references for all the possible return values. It's only possible to have one active connection on each HttpConnection object. Due to this we must make sure that we don't try to reconnect an active connection. If the create call was successful we can now set request headers. Since we don't need it we can call the finish function directly.

When we have a connection with the server the callback function httpFinished will be called.

  MAUtil::String contentLengthStr; 
  int responseBytes = mHttp.getResponseHeader("content-length", &contentLengthStr); 
  int contentLength = 0; 
  if(responseBytes == CONNERR_NOHEADER) 
  printf("no content-length response header\n"); 
  else { 
  printf("content-length : %s\n", contentLengthStr.c_str()); 
  contentLength = atoi(contentLengthStr.c_str()); 
  } 

First we check for the "content-length" response header, if it's not found we will recieve an CONNERR_NOHEADER response. If it's found we recieves the actual content length as an char array of numbers. It's then converted it to an int using the atoi function.

  if(contentLength >= CONNECTION_BUFFER_SIZE || contentLength == 0) { 
  printf("Receive in chunks..\n");
  mHttp.recv(mBuffer, CONNECTION_BUFFER_SIZE);
  } else {
  mBuffer[contentLength] = 0;
  mHttp.read(mBuffer, contentLength);
  }

If we don't have any content length or it's larger then our recieving buffer we can't just read all the data. We have to read multiple times until we reaches the end. This is done by calling the recv function of the HttpConnection object.

If we know the content length and the recieving data fits inside the buffer we can read it all directly. This is done by using the read function in HttpConnection.

The difference between the two is that recv specifies the total amount of bytes which it can recieve while read specifies the number of bytes it shall read. Each of these methods has its own callback functions. Depending on the function you use connRecvFinished or connReadFinished callback functions will be called.

  if(result >= 0)
  printf("connReadFinished %i\n", result);
  else
  printf("connection error %i\n", result);
  mHttp.close();

The connReadFinished callback function first check if the result is not negative. A negative result means an error might have happened. Check the return value against the API documentation. Positive results means that data was received. The connection shall be closed manually now since no more data will be received on this connection.

  if(result >= 0) {
  printf("connRecvFinished %i\n", result);
  mHttp.recv(mBuffer, CONNECTION_BUFFER_SIZE);
  return;
  }
  else if(result == CONNERR_CLOSED) {
  printf("Receive finished!\n");
  } else {
  printf("connection error %i\n", result);
  }
  mHttp.close();

The connRecvFinished callback function works a little bit different. If the result is positive we have received that amount of bytes. If so we can't close the connection since more data will be received. If it's negative we must check if it's CONNERR_CLOSED. CONNERR_CLOSED doesn't need to be an error. Usually it means that the sending server has sent its data and closed the connection to verify the receiver about it. When a negative value is returned the connection shall be closed.

#include <MAUtil/Moblet.h>
#include <mautil/connection.h>
#include <mastdlib.h>
#include <conprint.h>
#define CONNECTION_BUFFER_SIZE 1024
class MyMoblet : public MAUtil::Moblet, private MAUtil::HttpConnectionListener
{
public:
    MyMoblet();

    void httpFinished(MAUtil::HttpConnection *conn, int result);
    void connRecvFinished(MAUtil::Connection *conn, int result);
    void connReadFinished(MAUtil::Connection *conn, int result);
    void keyPressEvent(int keyCode);
private:
    void initiateConnection(const char* url);
    char mBuffer[CONNECTION_BUFFER_SIZE];
    MAUtil::HttpConnection mHttp;
    bool mIsConnected;
};
MyMoblet::MyMoblet() : mHttp(this)
, mIsConnected(false)
{
    printf("http connection tutorial.\n");
    printf("press softkeys to send http requests.\n");
    printf("press 0 to exit\n");
}
// connect to the given url if not other connection is active
void MyMoblet::initiateConnection(const char* url) {
    if(mIsConnected) {
        printf("already connected\n..");
        return;
    }
    printf("\nconnecting to %s", url);

    int res = mHttp.create(url, HTTP_POST);
    if(res < 0) {
        printf("unable to connect - %i\n", res);
    } else {
        mHttp.finish();
        mIsConnected = true;
    }
}
void MyMoblet::httpFinished(MAUtil::HttpConnection* http, int result) {
    printf("HTTP %i\n", result);

    MAUtil::String contentLengthStr;
    int responseBytes = mHttp.getResponseHeader("content-length", &contentLengthStr);
    int contentLength = 0;
    if(responseBytes == CONNERR_NOHEADER)
    printf("no content-length response header\n");
    else {
        printf("content-length : %s\n", contentLengthStr.c_str());
        contentLength = atoi(contentLengthStr.c_str());
    }
    if(contentLength >= CONNECTION_BUFFER_SIZE || contentLength == 0) {
        printf("Receive in chunks..\n");
        mHttp.recv(mBuffer, CONNECTION_BUFFER_SIZE);
    } else {
        mBuffer[contentLength] = 0;
        mHttp.read(mBuffer, contentLength);
    }

}
void MyMoblet::connReadFinished(MAUtil::Connection* conn, int result) {
    if(result >= 0)
    printf("connReadFinished %i\n", result);
    else
    printf("connection error %i\n", result);
    mHttp.close();

    mIsConnected = false;
}
void MyMoblet::connRecvFinished(MAUtil::Connection * conn, int result){
    if(result >= 0) {
        printf("connRecvFinished %i\n", result);
        mHttp.recv(mBuffer, CONNECTION_BUFFER_SIZE);
        return;
    }
    else if(result == CONNERR_CLOSED) {
        printf("Receive finished!\n");
    } else {
        printf("connection error %i\n", result);
    }
    mHttp.close();
    mIsConnected = false;
}
// Press 0 to exit. Soft left and soft right will initiate new connections
void MyMoblet::keyPressEvent(int keyCode) {
    switch(keyCode) {

    case MAK_0:
        maExit(0);
        break;

    case MAK_SOFTLEFT:
        initiateConnection("http://www.example.com/");
        break;
    case MAK_SOFTRIGHT:
        initiateConnection("http://www.mosync.com/");
        break;
    }
}
extern "C" int MAMain() {
    InitConsole();
    gConsoleLogging = 1;
    MAUtil::Moblet::run(new MyMoblet());
}

Using Connection Sockets

Here we take a look at how to use the MAUtil's Connection API to communicate over sockets using TCP. We will illustrate how to use them by making a simple FTP client.

An FTP client begins by setting up a socket to the FTP server, authorize itself and then continues by sending instructions. All communication is done in plain text which makes the protocol both easy to understand and use. For further information about the FTP protocol see cr.yp.to/ftp.html.

Implementation

We will implement all functionality as functions in a class inherited from Moblet, so we begin by creating a project from a Moblet template, adding a few #include directives, and declaring inheritance from the MAUtil::ConnectionListener class:

#include <MAUtil/Moblet.h> 
#include <MAUtil/Connection.h> 
#include <MAUtil/Util.h> 
#include <conprint.h>
#include <mastdlib.h>
using namespace MAUtil;
class MyMoblet : public Moblet, ConnectionListener 
{

Then add the member variables of the class, a Connection instance, and a temporary string buffer. The string buffer will be used to store the incoming responses from the server:

private:
Connection mConnection;
char lineBuffer[1024];

We continue by defining the Constructor. In the initialization list we initialize the connection by passing a pointer to this (the MAUtil::ConnectionListener). In the constructor we connect the connection to a socket, i.e. the FTP server we're going to communicate with. FTP communication defaults to port 21, but in some cases FTP servers may use other ports. We verify that the connection has been successfully initiated by checking the return value from connect.

public: 
MyMoblet() : mConnection(this)
{
    int res = mConnection.connect("socket://ftp.sunet.se:21");
    if(res < 0) 
    {
        maPanic(res, "mConnection.connect failed");
    }
}

Now we will add some helper functions to receive, parse, and send the FTP response and requests. First we add a function that receives incoming data to the temporary string buffer:

void getNextFtpResponse()
{
    mConnection.recv(lineBuffer, 1024);
}

When the response has been received the connRecvFinished function derived from the ConnectionListener, which we will implement later, is invoked. Next we implement a function to put an FTP request. It adds a line breaking sequence that conforms to the FTP standard and writes the request to the connection. The connWriteFinished function will be invoked when the request has been written.

void putFtpRequest(const char *req)
{
    char temp[1024];
    int len = sprintf(temp, "%s\015\012", req);
    mConnection.write(temp, len);
}

Finally, we add a function that parses the response code of a response line. (The link to the FTP protocol description at the top of this guide describes the format of a response.)

We first trim the spaces in the beginning and then parse the following number:

int parseFtpResponseCode(const char *lineBuffer)
{
    int i=0;
    char temp[16];
    while(lineBuffer[i]==' ') { i++; } 
    
    // trim spaces in the beginning
    while(isdigit(lineBuffer[i])) temp[i++] = lineBuffer[i];
    temp[i] = 0;
    return atoi(temp);
}

Now that the helper functions are ready we can implement the actual communication. First we implement the connectFinished function derieved from the ConnectionListener which checks if everything went well and if that is the case, receives the next FTP server response.

void connectFinished(Connection* conn, int result)
{
    if(result < 0) 
    {
        printf("mConnection.connectFinished failed");
        return;
    }
    getNextFtpResponse();
}

The connWriteFinished will look exactly the same. Whenever we've sent an FTP request we want to receive a new FTP response.

void connWriteFinished(Connection* conn, int result)
{
    if(result < 0)
    {
        printf("mConnection.write failed");
        return;
    }
    getNextFtpResponse();
}

When we've received a response from the server we can decide on what to do next. The final function connRecvFinished derived from the ConnectionListener will be called when a response has been received. First we split the lines of the response into a list of strings, one for each line. The response code will be the same for each line, so we parse the response code of the first line. By analyzing the response code, the client program can determine what state the FTP connection is in and choose what to do next.

We will only implement a few steps in the initial handshaking procedure. After the PASV command has been sent, a response with a new IP address and port is recieved. This IP address should be used to set up a data connection. All data traffic will be handled over this connection. Even the result from requests like LIST, which list all files in a directory. Implementing this functionality is left as an exercise for the reader.

void connRecvFinished(Connection* conn, int result)
{
    if(result < 0) 
    {
        printf("mConnection.recv failed");
        return;
    }

    // We may have recieved several lines in one response, 
    // but all of them will begin with the same response code.
    Vector<String> responses;
    stringSplit(lineBuffer, "\015\012", responses);

    // the last one will always be an empty string
    responses.resize(responses.size()-1); 
    for(int i = 0; i < responses.size(); i++) printf("%s", responses[i].c_str());
    int code = parseFtpResponseCode(responses[0].c_str());
    switch(code)
    {
    // 220 welcome - we respond with a user (anonymous in this case)
    case 220: putFtpRequest("USER anonymous"); break;

    // 331 identify yourself in a password - we can send any password as we're anonymous.
    case 331: putFtpRequest("PASS dummy"); break;

    // 230 thanks - we enter passive mode
    case 230: putFtpRequest("PASV"); break;
    }
}
};

If you've done everything right, the result will look like this:

Creating a Bluetooth Server

Many people are developing Bluetooth applications in MoSync. Some of the most interesting applications involve creating a new Bluetooth service so that the user’s phone can receive incoming messages on Bluetooth and act on them. In this tutorial we take a look at using the MAUtil::Server class to provide Bluetooth services.

The Server Base Class

In the MoSync MAUtil library there is a class called Server. It is a base class that you can adapt to accept network connections over Bluetooth and TCP. You create a new Bluetooth service by creating a new Server instance and inheriting from ServerListener. Your class becomes a wrapper around Server and can process both incoming and outgoing messages.

The ServerListener interface allows your service class to respond to events raised by your Server instance. There are two methods that you need to implement: serverAccepted and serverAcceptFailed. These methods inform your application when a new connection has been made to your server, or when an attempt to connect has failed.

When you receive a new connection, the serverAccepted method is called, and it is passed a pointer to a new Connection object. This is the same class as you would use for outgoing connections so all of the same methods for reading and writing data are available. The only difference is that you’ve got to code responses to incoming data.

A very simple Server implementation would look like this:

#include <MAUtil/Moblet.h>
#include <MAUtil/Server.h>
#include <conprint.h>
using namespace MAUtil;
class MyServer : public ServerListener
{
	private:
		Server mServer;
		MAHandle mConn;
	public:
		MyServer() : mServer(this), mConn(NULL)
		{
		}
		~MyServer()
		{
			//Close the server before we exit
			if(mServer.isOpen())
				mServer.close();
		}
		void MyServer::connect()
		{
			if(mServer.isOpen())
				lprintfln("Already open");
			else
			{
				//Start accepting incoming TCP requests on port 81
				mConn = mServer.start("socket://8103");
				if(mConn < 0)
					lprintfln("Service failed - is the port blocked?");
				else
					lprintfln("Service started");
			}
		}
		//ServerListener
		void MyServer::serverAcceptFailed(Server* server, int result)
		{
			lprintfln("Connection failed");
		}
		void MyServer::serverAccepted(Server* server, Connection* conn)
		{
			lprintfln("Connection accepted");
		}
};
class MyMoblet : public Moblet
{
	public:
		MyMoblet()
		{
			MyServer myServer;
			myServer.connect();
		}
};
extern "C" int MAMain()
{
	Moblet::run(new MyMoblet());
	return 0;
};

As you can see from the code, the class MyServer creates a new server and binds itself to TCP port 81. Any requests to the phone on that port will now be answered by MyServer.

Creating Servers for Bluetooth Connections

Binding to Bluetooth addresses is a little more complex. Instead of simply binding to a port you need to bind to the Bluetooth address of the device, and provide a service UUID.

Each Bluetooth service has its own UUID (universally unique identifier). These are common across platforms, just as TCP ports are. If you create a brand-new service, you should generate a new UUID for it. If you are implementing an existing service (such as OBEX Push), then you should use the existing UUID. Common UUIDs have been defined in the file MAUtil/mauuid.h.

When Bluetooth clients are searching for your service, they will need to know what the UUID is. If you are writing the client software as well, you’ll need to use the UUID to discover the service. See our tutorial on Discovering Devices and Services with Bluetooth for more information.

In the MoSync SDK, Bluetooth service UUIDs are defined as being a struct of an int[4]. Bluetooth UUIDs are 32 bytes long, but large parts of the UUID are common to all Bluetooth UUIDs. If you want to create your own UUID, you would need to check that it isn’t being used by any other Bluetooth service, and also ensure that its unique segment (the first int in the struct) ANDs with 0x1000 (4096). The following is a line from mauuid.h, defining the UUID for the serial port service.

DEFINE_BTMAUUID(SerialPort_Service_MAUUID, 0x1101);

Its unique segment is 0x1101. The first "1" signals that it is a specific service, and not a service collection (compare with DEFINE_BTMAUUID(RFCOMM_PROTOCOL_MAUUID, 0x0003);). The remaining value 0x101 (257) is the part that matches the standard definition for serial port.

Creating Server IDs

Your UUID must be unique. In this example, we will use a value of 355. We can then define our new service UUID as follows:

DEFINE_BTMAUUID(Example_Service_MAUUID, 0x1163);

The format of a Bluetooth service URL is:

btspp://localhost:<service uuid>[;name=<plain text name of the service>]

If we were creating a new service, we would need to have created an MAUUID which we could write to the string. When translated, our MAUUID is 0000116300001000800000805f9b34fb.

Formatting Connection URLs

This little function will create a valid URL:

void MyServer::formatUrl(char* output, MAUUID& serviceID, const char* servicename)
{
	sprintf(output, "btspp://localhost:%08x%08x%08x%08x;name=%s\0", serviceID.i[0], serviceID.i[1], serviceID.i[2], serviceID.i[3], servicename);
}

You can now use the URL to start the server. The connect method takes this URL instead.

#include <MAUtil/Moblet.h>
#include <MAUtil/Server.h>
#include <MAUtil/mauuid.h>
#include <conprint.h>
using namespace MAUtil;
DEFINE_BTMAUUID(Example_Service_MAUUID, 0x1163);
//This class sets up the server connection, and manages the bindings.
class MyServer : public ServerListener
{
	private:
		Server mServer;
		MAHandle mConn;
		
		void MyServer::formatUrl(char* output, const MAUUID& serviceID, const char* servicename)
		{
			sprintf(output, "btspp://localhost:%08x%08x%08x%08x;name=%s\0", serviceID.i[0], serviceID.i[1], serviceID.i[2], serviceID.i[3], servicename);
		}
	public:
		MyServer() : mServer(this), mConn(NULL)
		{
		}
		~MyServer()
		{
			//Close the server before we exit
			if(mServer.isOpen())
				mServer.close();
		}
		void MyServer::connect()
		{
			if(mServer.isOpen())
				lprintfln("Already open");
			else
			{
				//Start accepting incoming BT requests for Example_Service_MAUUID
				char buffer[255];
				const char* servicename = "Example Service";
				formatUrl(&buffer[0], Example_Service_MAUUID, servicename);
				lprintfln("url: %s", buffer);
				mConn = mServer.start(buffer);
				if(mConn < 0)
					lprintfln("Service failed");
				else
					lprintfln("Service started");		
			}
		}
		//ServerListener
		void MyServer::serverAcceptFailed(Server* server, int result)
		{
			lprintfln("Connection failed");
		}
		void MyServer::serverAccepted(Server* server, Connection* conn)
		{
			lprintfln("Connection accepted");
			mConnHandler->start(conn);
		}
};
class MyMoblet : public Moblet
{
	private:
		MyServer myServer; 
	public:
		MyMoblet()
		{
			myServer.connect();
		}
};
extern "C" int MAMain()
{
	Moblet::run(new MyMoblet());
	return 0;
};

This won’t let you start accepting connections though. This is just the server binding information. To accept connections, you need to create a ConnectionListener.

Accepting Connections

If you’ve run the above examples, you will notice that neither the serverAccepted or the serverAcceptFailed methods have been called. To make the server binding work, you need to call the accept method, and pass it a ConnectionListener.

ConnectionListener will be familiar to anyone who has developed a network client in MoSync. It responds to connection events from the Connection class. The ConnectionListener has the following methods you need to implement:

 void connectFinished(Connection* conn, int result);
 void connRecvFinished(Connection* conn, int result);
 void connWriteFinished(Connection* conn, int result);
 void connReadFinished(Connection* conn, int result);

When your server starts, it will return you a normal Connection object. Just as when you are developing a client application, you need to be able to respond to incoming and outgoing data, and to be able to read from and write to the stream. The ConnectionListener you will create will do this for you, and actually implement the details of your protocol.

Creating ConnectionListeners

A common way to develop this ConnectionListener is to create a connection handler. This is the class which will maintain the connection state and manage the data flow.

class MyConnectionHandler : public ConnectionListener
{
	private:
		Connection* mConn;
		char buffer[64];
	public:
		MyConnectionHandler();
		~MyConnectionHandler();
		//Provide a method to tell the connection handler to start receiving data
		void MyConnectionHandler::start(Connection* conn)
		{
			mConn = conn;
			//Wait to receive a few bytes
			mConn->recv(&buffer, 63); //Don't receive more than the buffer size.
		}
		//ConnectionListener interface
	 void MyConnectionHandler::connectFinished(Connection* conn, int result)
	 {
	 	lprintfln("Connection to a client has been established");
	 }
	 void MyConnectionHandler::connRecvFinished(Connection* conn, int result)
	 {
	 	lprintfln("%d bytes have been received.", result);
	 }
	 void MyConnectionHandler::connWriteFinished(Connection* conn, int result)
	 {
	 	lprintfln("%d bytes have been written", result);
	 }
	 void MyConnectionHandler::connReadFinished(Connection* conn, int result)
	 {
	 	lprintfln("%d bytes have been read", result);
	 }
};

This example is just about as simple as it can be. The class inherits from ConnectionListener and provides the methods for receiving notification of data reads and writes. When one of these is called, it just writes the notification to the console.

Processing a connection

There is also a method start. This is so we can start the connection handler with a valid connection, and it can start requesting data from the stream. As an example, we’re going to create a server that receives data, counts the number of bytes it has received in total, and respond to the client with this value. We’ve got a buffer to read into, but we’re not really interested in the data, just the values, so we can write the data to the console and keep track of the quantity. When data is received, we’re going to increase the total counter, create a text value to that amount and write it to the output stream.

	 void MyConnectionHandler::connRecvFinished(Connection* conn, int result)
	 {
	 	if(result > 0)
	 	{
				lprintfln("%d bytes have been received.", result);
				//Increase the byte counter
				total += result;
				//Write the data to the console
				lprintfln("%s", buffer);
				//Write the running total to the output stream
				sprintf(&writeBuffer[0], "%9d", total);
				mConn->write(&writeBuffer, 10);
				//Reset the read buffer
				memset(&buffer, 0, 64);
				//Receive some more data
				mConn->recv(&buffer, 63);
	 	}
	 	else
	 	{
	 		//An error condition has been reached
	 		lprintfln("Error - %d", result);
	 	}
	 }

We’ve also put an error check in there to ensure that no error codes have been sent.Now we’ve got a connection handler that can read and write data, we can call the accept method on the Server.

		{
			if(mServer.isOpen())
				lprintfln("Already open");
			else
			{
				//Start accepting incoming BT requests for Example_Service_MAUUID
				char buffer[255];
				const char* servicename = "Example Service";
				formatUrl(&buffer[0], Example_Service_MAUUID, servicename);
				lprintfln("url: %s", buffer);
				mConn = mServer.start(buffer);
				if(mConn < 0)
					lprintfln("Service failed");
				else
				{
					lprintfln("Service started");
					//Accept the connection
					mServer.accept(new MyConnectionHandler());
				}
			}
		}

Once the server has bound to the port or service, the serverAccepted method is called, and you can start your connection handler receiving data.

In a more sophisticated example, you would also need a listener to the connection handler for it to report errors to, and to close the connection when it has finished. The complete listing is below

#include <MAUtil/Moblet.h>
#include <MAUtil/Server.h>
#include <MAUtil/mauuid.h>
#include <conprint.h>
using namespace MAUtil;
DEFINE_BTMAUUID(Example_Service_MAUUID, 0x1163);
//This class handles the connection and implements the details of the protocol
class MyConnectionHandler : public ConnectionListener
{
	private:
		Connection* mConn;
		char buffer[64];
		char writeBuffer[10];
		int total;
	public:
		MyConnectionHandler() {}
		//Provide a method to tell the connection handler to start receiving data
		void MyConnectionHandler::start(Connection* conn)
		{
			total = 0; //Receive 0 bytes so far
			mConn = conn;
			//Wait to receive a few bytes
			mConn->recv(&buffer, 63); //Don't receive more than the buffer size.
		}
		//ConnectionListener interface
	 void MyConnectionHandler::connectFinished(Connection* conn, int result)
	 {
	 	lprintfln("Connection to a client has been established");
	 }
	 void MyConnectionHandler::connRecvFinished(Connection* conn, int result)
	 {
	 	if(result > 0)
	 	{
				lprintfln("%d bytes have been received.", result);
				//Increase the byte counter
				total += result;
				//Write the data to the console
				lprintfln("%s", buffer);
				//Write the running total to the output stream
				sprintf(&writeBuffer[0], "%9d", total);
				mConn->write(&writeBuffer, 10);
				//Reset the read buffer
				memset(&buffer, 0, 64);
				//Receive some more data
				mConn->recv(&buffer, 63);
	 	}
	 	else
	 	{
	 		//An error condition has been reached
	 		lprintfln("Error - %d", result);
	 	}
	 }
	 void MyConnectionHandler::connWriteFinished(Connection* conn, int result)
	 {
	 	lprintfln("%d bytes have been written", result);
	 	//Clear the write buffer
	 	memset(&writeBuffer, 0, 10);
	 }
	 void MyConnectionHandler::connReadFinished(Connection* conn, int result)
	 {
	 	lprintfln("%d bytes have been read", result);
	 }
};
//This class sets up the server connection, and manages the bindings.
class MyServer : public ServerListener
{
	private:
		Server mServer;
		MAHandle mConn;
		MyConnectionHandler* mConnHandler;
		void MyServer::formatUrl(char* output, const MAUUID& serviceID, const char* servicename)
		{
			sprintf(output, "btspp://localhost:%08x%08x%08x%08x;name=%s\0", serviceID.i[0], serviceID.i[1], serviceID.i[2], serviceID.i[3], servicename);
		}
	public:
		MyServer() : mServer(this), mConn(NULL)
		{
		}
		~MyServer()
		{
			//Close the server before we exit
			if(mServer.isOpen())
				mServer.close();
		}
		void MyServer::connect()
		{
			if(mServer.isOpen())
				lprintfln("Already open");
			else
			{
				//Start accepting incoming BT requests for Example_Service_MAUUID
				char buffer[255];
				const char* servicename = "Example Service";
				formatUrl(&buffer[0], Example_Service_MAUUID, servicename);
				lprintfln("url: %s", buffer);
				mConn = mServer.start(buffer);
				if(mConn < 0)
					lprintfln("Service failed");
				else
				{
					lprintfln("Service started");
					//Accept the connection
					mConnHandler = new MyConnectionHandler();
					lprintfln("Created the handler");
					lprintfln("Requesting accept");
					mServer.accept(mConnHandler);
				}
			}
		}
		//ServerListener
		void MyServer::serverAcceptFailed(Server* server, int result)
		{
			lprintfln("Connection failed");
		}
		void MyServer::serverAccepted(Server* server, Connection* conn)
		{
			lprintfln("Connection accepted");
			mConnHandler->start(conn);
		}
};
class MyMoblet : public Moblet
{
	public:
		MyMoblet()
		{
			MyServer myServer;
			myServer.connect();
		}
};
extern "C" int MAMain()
{
	Moblet::run(new MyMoblet());
	return 0;
};

Creating Bluetooth Clients

In our Discovering Devices and Services with Bluetooth tutorial we demonstrated how the MAUtil::BluetoothDiscoverer class can be used to locate nearby devices and find out which Bluetooth services they support. Once you’ve discovered a device and a service you will need to write a client for that service and open a data connection to the server. That's what we will be doing in this tutorial.

Opening Connections

To create a connection to the Bluetooth device that you want to communicate with, you can use the Connection class in the MAUtil library (#include <MAUtil/Connection.h>). The Connection class wraps up common connection commands into one easy-to-use object.

Creating ConnectionListeners

Creating Connection objects is discussed at length in the tutorial Downloading Data from the Internet, but the one thing you do have to do though is to implement ConnectionListener. The ConnectionListener has the following methods you need to implement:

void connectFinished(Connection* conn, int result);
void connRecvFinished(Connection* conn, int result);
void connWriteFinished(Connection* conn, int result);
void connReadFinished(Connection* conn, int result);

When the Connection object reads to writes data, it will inform your ConnectionListener of the result.

//ConnectionListener
void connectFinished(Connection* conn, int result)
{
 lprintfln("Connection established");
}
void connRecvFinished(Connection* conn, int result)
{
 lprintfln("Received %d bytes", result);
}
void connWriteFinished(Connection* conn, int result)
{
 lprintfln("Wrote %d bytes", result);
}
void connReadFinished(Connection* conn, int result)
{
 lprintfln("Read %d bytes", result);
}

To create the Connection, you need to be able to format a URL to the desired Bluetooth server correctly. This is the only real difference between connecting to a Bluetooth service and connecting to an HTTP resource on the Internet.

This tutorial assumes that you’ve either already followed the discovery processes in our tutorial Discovering Devices and Services with Bluetooth. That tutorial explains how to find the service you want to connect to, and introduces the classes BtDevice and BtService.

Formatting Bluetooth URLs

When you want to create a URL to connect to a Bluetooth service, you need the MABtAddr address class from BtDevice and the port number from BtService. The example we are working through today assumes you’ve already got the both a BtDevice and a BtService.

The Bluetooth URL is in the format:

btspp://<device address>:<service port>

The device address is in an MABtAddr object in BtDevice.address. The MABtAddr is a struct that contains byte[6]. Each of these bytes needs to be converted to two-character hex value in array order.

This little function will convert it for you:

void BluetoothClient::formatConnection(char* output, BtDevice& device, int port)
{
	MABtAddr a = device.address;
	sprintf(output, "btspp://%02x%02x%02x%02x%02x%02x:%i",
		a[0], a[1], a[2], a[3], a[4], a[5], port);
}

Reading and Writing to the Service

Once connected, you’ve got the same Connection object as you have for connecting to the Internet. You can read and write into the connection.

In this example, we are going to create a client which is for the Bluetooth service created for the tutorial Creating a Bluetooth Server. In that tutorial, the service simply receives a stream of bytes, counts them, and then returns a running total to the client. Our client is going to connect to that server, send a short string, and then listen for the count to be returned.

To do this, we need to expand the implementation of ConnectionListener we produced earlier. The first stage is to make the connection to the correct URL. This means we need to write a short method to start the connection:

void BluetoothClient::connect(BtDevice& device, BtService& service)
{
	char buffer[100];
	formatConnection(&buffer[0], device, service.port);
	mConn.connect(buffer);
}

We use the formatConnection method from earlier to create the URL, and make a connection. If successful, our connectFinished method will be called:

void BluetoothClient::connectFinished(Connection* conn, int result)
{
 lprintfln("Connection established");
 //Connection finished, start sending data
 mConn.write("123456", 6);
}

Once the connection is open, we can write data into it. As with all Connection objects, the write is asynchronous, so don’t write from local variables as they can go out of scope before the write has completed. Here, we are just writing six bytes representing the characters one to six. Once the write has finished, our connWriteFinished method will be called.

void BluetoothClient::connWriteFinished(Connection* conn, int result)
{
 lprintfln("Wrote %d bytes", result);
 //Listen for response
 mConn.recv(&readBuffer, 63);
}

We know that we’ve written data to the server, so now we can wait for the server to respond with the lenght of the data we’ve sent. There is a char[64] already declared to read the response into. When data has been received, our connRecvFinished method will be called.

void BluetoothClient::connRecvFinished(Connection* conn, int result)
{
 lprintfln("Received %d bytes", result);
 //Received the data
 lprintfln("Server response: %s", readBuffer);
 //Finished
 mConn.close();
}

We can echo the server’s response to the screen, and hopefully it tells us that we’ve sent six bytes. Now that we’ve completed our exchange, we can close the connection. Obviously, this is a simple example to demonstrate the process, but all application level protocols can be implemented in this fashion.

The Completed Client

There is a conversation between the client and the server, but the responses and the actions will depend on the protocol you wish to create. The complete source code follows:

#include <MAUtil/Moblet.h>
#include <MAUtil/Connection.h>
#include <MAUtil/BluetoothDiscovery.h>
#include <conprint.h>
using namespace MAUtil;
class BluetoothClient : public ConnectionListener
{
	private:
		Connection mConn;
		char readBuffer[64];
		void BluetoothClient::formatConnection(char* output, BtDevice& device, int port)
		{
			const byte* a = device.address.a;
			sprintf(output, "btspp://%02x%02x%02x%02x%02x%02x:%i",
				a[0], a[1], a[2], a[3], a[4], a[5], port);
		}
	public:
		BluetoothClient() : mConn(this)
		{}
		~BluetoothClient()
		{
			if(mConn.isOpen())
				mConn.close();
		}
		void BluetoothClient::connect(BtDevice& device, BtService& service)
		{
			char buffer[100];
			formatConnection(&buffer[0], device, service.port);
			mConn.connect(buffer);
		}
		//ConnectionListener
	 void BluetoothClient::connectFinished(Connection* conn, int result)
	 {
	 	lprintfln("Connection established");
	 	//Connection finished, start sending data
	 	mConn.write("123456", 6);
	 }
	 void BluetoothClient::connRecvFinished(Connection* conn, int result)
	 {
	 	lprintfln("Received %d bytes", result);
	 	//Received the data
	 	lprintfln("Server response: %s", readBuffer);
	 	//Finished
	 	mConn.close();
	 }
	 void BluetoothClient::connWriteFinished(Connection* conn, int result)
	 {
	 	lprintfln("Wrote %d bytes", result);
	 	//Listen for response
	 	mConn.recv(&readBuffer, 63);
	 }
	 void BluetoothClient::connReadFinished(Connection* conn, int result)
	 {
	 	lprintfln("Read %d bytes", result);
	 }
};

Discovering Devices and Services with Bluetooth

Implementing Bluetooth in your application is usually done in three stages. Firstly, there is device discovery: getting the phone to scan for other devices in range. Secondly, there is a service discovery: querying a discovered device to see which protocols and services it supports. Lastly, there is the implementation of a service, a specific transfer of data. This tutorial covers the first two steps: discovering devices and services.

Device Discovery

The first stage working with Bluetooth is discovering other Bluetooth devices. These could be other phones or mobile devices, laptop or desktop computers or any other Bluetooth-enabled device.

Note: The MoRE emulator you use to develop and test MoSync applications supports Bluetooth if the PC you are using supports it. Developers with Bluetooth enabled (as is very common on laptops) will see their PC search for devices just as their phones will.

We provide several C++ Bluetooth discovery classes in the MoSync SDK. These classes perform an asynchronous search of Bluetooth devices, and return information about each device, including its name and its unique address. To use the Bluetooth discovery classes, include the header file MAUtil/BluetoothDiscovery.h in your application.

BluetoothDeviceDiscoveryListener

To implement Bluetooth discovery, you need to create a class which will respond to Bluetooth events. If you are creating a MAUI application, this will often be a MAUI::Screen class. In the following example, we've built a screen called Devices. It searches for and reports on Bluetooth devices in detectable range. When we define this class, we make it inherit from the interface class BluetoothDeviceDiscoveryListener:

class Devices : public Screen, public BluetoothDeviceDiscoveryListener
{

We also need it to implement the two methods defined in BluetoothDeviceDiscoveryListener, btNewDevice and btDeviceDiscoveryFinished:

#include <MAUtil/BluetoothDiscovery.h>
... 
    //Members for the BluetoothDeviceDiscoveryListener
    void btNewDevice (const BtDevice &dev);
    void btDeviceDiscoveryFinished (int state);

To perform a Bluetooth device discovery, you will need an instance of BluetoothDiscoverer: