This tutorial will guide you through the process of developing "native extensions" in order to access iPhone and Android platform specific services from your ELIPS Studio Flex application.

More specifically, this sample shows how to play music natively on iPhone and Android, i.e.:

• Use the iPod library on the iPhone
• Play a music file on Android

Native extensions for iPhone and for Android are available on MS Windows and MAC OSX.

Prerequisites: for iPhone

In order to create a native extension for iPhone, you need to have a Mac with XCode 3.2.1 / iPhone SDK 3.1 (or higher), as available from the iphone Dev Center.

Prerequisites: for Android

Android setup is a little bit more complex, this is why we decided to detail it a bit more.
Warning: Make sure Flex / Flash Builder is not running during this setup, as it is based on Eclipse, and might interfere with the Android Development Tools installation.

Tools Installation: In order to create a native extension for Android, you need to install the following tools:

• Eclipse 3.4 (or higher): Download and install Eclipse IDE for Java Developers from here.


• ADT plugin (Android Development Tools for Eclipse): follow the steps here, "Installing the ADT Plugin"->"Downloading the ADT Plugin", in order to install the ADT plugin in your Eclipse IDE.
  Tip: if the "standard installation mechanism" does not work, follow the steps described in "Troubleshooting ADT Installation", by downloading the ADT plugin zip file, and installing it from your hard drive.
  


• Android SDK with with Android 2.2 SDK Package (Android SDK needed to develop code for Android):
  • Download and unzip the Android SDK from here
  • Launch the "SDK Setup.exe" file contained in this SDK to download desired SDK package(s).
  • Go to the "Available Packages" tab, click on the "+" icon, and tick "SDK Platform Android 2.2, API 8...", then hit "Install Selected" button. Download and installation will start. This process can take several minutes.
  • If you wish to use the Android emulator, click on "Virtual Devices" tab, and create a new one. This process can take several minutes.
    Tip: if this program fires an error "Failed to fetch URL https://...", go to "Settings" tab, and tick "Force https://... sources to be fetched...". Go back to the "Available Packages" and hit the "Refresh" button.


• Android NDK, r4 (Android Native Development Kit, required by ELIPS Studio to generate the native extension): download the Android NDK for Windows, or for Mac OS X, and unzip it to your place of choice on your harddrive.
  Warning: Newest Android NDK version "r4b" is not yet supported by ELIPS Studio. Until it is supported, you must use the version r4 (from the links above). Note that differences are minimal, and will most probably not impact you.
  


• [For PC running Microsoft Windows] cygwin 1.7 (required by Android NDK): at least the GNU make utility. Note: This is not required on MAC.
  • Download and execute cygwin setup program from cygwin site
  • During setup process, in "Select Package" screen, make sure to select:
    • "make: the GNU version of the make utility" under the "Devel" category.
    • "bash: the GNU Bourne Again SHell" under the "base"/"shell" categories.
      Tip: You can type "make" or "bash" in the search box in the "Select Package" screen, to locate easily the utilities.
      
    
    
  • To finish, create the CYGWIN Environment Variables required by ELIPS Studio to locate your Cygwin path:
    
    • variable: CYGWIN, value: [your cygwin path] ex: "C:\cygwin"
    • note: path to "\cygwin\bin" shall be removed as it can create conflicts

• Start Eclipse, set your Eclipse workspace
• Configure the Android SDK Path:
• Window -> Preferences
• Android tab -> Browse button
• Browse to the folder where you have unzipped the Android SDK (make sure you point to the SDK, not the NDK)

Creating your project in ELIPS Studio

Setting up the Project

1. Create a new Flex project in ELIPS for Flex Builder



 

2. In the project properties, select iPhone target then set the iPhone target properties correctly, as described in the "Building your application for the iPhone" tutorial.
   Note: to use native extensions, you need to use the "Generate XCode project" build mode for your iPhone app.



 

3. In the project properties, select Android 1.6 320x480 target then set the Android target properties correctly, as described in the "Deploying ELIPS Studio3 apps to Android phones" tutorial, plus the two additional setting:
   • User Native Project Directory: This is where the Android Java project will be generated, best is to set it to a subfolder of your Android-Eclipse workspace
   • NDK Directory: The installation folder of the Android NDK

   

4. Once your project is setup, add a new ActionScript Class for creating a native extension. Right click on the “src” folder of your project in the Flex Navigator panel then choose “New” -> “ActionScript Class”
5. In the New ActionScript Class panel, give it a name then click “Finish"



 

6. Edit the “.as” file created as a result of the previous step and copy the code below.
   The music_playback function is actually a so-called native extension. The [ElipsPlatformExtension()] key means that the function will be replaced by a native implementation for the platform passed in parameter (here iPhone and Android), if available. The code here is considered as a fallback for platforms where the native implementation is not found (including in simulation).



package
{
    public class NativePlayer
    {
        public function NativePlayer()
        {
        }

        [ElipsPlatformExtension(platforms="iPhone OS 3.0,Android 1.6")]
        public function music_playback():Boolean
        {
            trace ("Play Music from Native Library");
            return false;
        }
    }
}
 

7. Going back to your application “.mxml” file, write a simple UI consisting in a label and a button. On button touchTap, call the play_music() function.



<?xml version="1.0" encoding="utf-8"?>
<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute">

    <mx:Label id="title" x="0" y="40" width="100%" textAlign="center"
    text="Hello Music Player" fontSize="16"/>

    <mx:VBox x="0" y="100" width="100%" horizontalAlign="center" verticalAlign="middle" >
        <mx:Button id="playMusicButton" height="40" width="200" label="Play my music"
        fontSize="12" touchTap="play_music()"/>
        <mx:Label id="currentMusic" text=""/>
    </mx:VBox>

</mx:WindowedApplication>
 

 

8. Now, implement the play_music() function in ActionsScript. The play_music() function calls the native extension created previously and changes the label according to the boolean that is returned.



<mx:Script>
<![CDATA[

var player:NativePlayer = new NativePlayer();

private function play_music():void
{
    if (player.music_playback()) {
        currentMusic.text="Playing your music library."
    } else {
        currentMusic.text="Your music library is empty."
    }
}

]]>
</mx:Script>
 

9. At this stage, you can run in simulation to see the generic behavior (with the "ActionScript" fallback for the native extension).

 

[iPhone] Implementing and Building Native Extensions

10. Select the "iPhone" target then press the "Build Package For Current Device" button in the ELIPS for Flex Builder toolbar, then select your project name in the drop down list.

    

     

    This will generate the XCode project for your application, together with the native extension code. Note that a new folder has been added to your project called "extensions". It contains the template ".c" and ".h" files that you will need to implement the native part of the music_playback() method.
    The build result in the console will point you to the generated xCode project location.

    
    Upload finished (XCODE project available under
    D:\Flex_Elips3\MusicPlaybackSample\iPhone_Release\xcode)
     

 

11. Copy the generated XCode project folder to your Mac (i.e D:\Flex_Elips3\MusicPlaybackSample)
12. In Mac Finder, go to “/iPhone_Release/xcode” in the generated XCode project folder. Copy and rename the "ElipsExt_template" folder into "ElipsExt". This way you will not loose your changes if you regenerate the XCode project.
13. In the "ElipsExt" folder you just create, open the ElipsExt.xcodeproj project in XCode (simply double-click)
14. You first need to manually add all the .h and .c auto-generated files into the ElipsExt project. Just right-click on the “other sources” project folder then “Add” -> “Existing Files” then add all .h/.c files located in the "ElipsExt/src" folder. Among those can be found:
    - as_model_native.h: that define the native mapping function that can be used to convert C to AS objects.
    - NativePlayer.c: the c stub to be used for the iPhone native implementation part of the native extension method.
    
15. Then add a new objective-c “.m” source file to implement the native part of the extension and access the iPhone libraries. Right-click on the “other sources” project folder then “Add” -> “New File”. From there, choose “Objective-C Class”





 

16. Edit the “.m” created file. You are going to implement a function in C that will make use of the iPhone MediaPlayer class to create a native player. Refer to the iPhone development material for more details about objective-C and iPhone libraries.



//
// playback.m
// ElipsExt
//
// Created by Emmanuel Niclot on 19/03/10.
// Copyright 200 __MyCompanyName__. All rights reserved.
//

#import "playback.h"
#import <MediaPlayer/MediaPlayer.h>

@implementation playback

void ipod_playback() {
    // instantiate a music player
    MPMusicPlayerController *myPlayer = [MPMusicPlayerController applicationMusicPlayer];

    // assign a playback queue containing all media items on the device
    [myPlayer setQueueWithQuery: [MPMediaQuery songsQuery]];

    // Shuffle Mode
    [myPlayer setShuffleMode: MPMusicShuffleModeSongs];

    // start playing from the beginning of the queue
    [myPlayer play];
}

@end
 

 

17. Edit the auto-generated NativePlayer.c file. declare the ipod_playback() function so it can be used in the native extension method. Return AStrue, which is the C to AS equivalent of true, as your native extension method has to return a Boolean.


#include "as_native_model.h"
#include "NativePlayer.h"

extern void ipod_playback();

ASBool NativePlayer_as_i_music_playback(ASContext ctxt, ASObject thiz)
{
   // TODO: Add your code here
   ipod_playback();
   return ASTrue;
}

 

18. Compile the library for iPhone Device / Release. A “.a” lib will be generated in your main project.”/Release” folder
19. Open the main XCode project located in the parent folder
20. As the native extension lib was compiled previously, you can now compile the whole project for iPhone Device / Release. Then run it on target. Providing your iPod library is not empty, you will be able to play it from the ELIPS sample app. Amazing, isn’t it ?

[Android] Implementing and Building Native Extensions

21. Select the "Android" target then press the "Build Package For Current Device" button in the ELIPS for Flex Builder toolbar, then select your project name in the drop down list.

    

     

    This will generate the Eclipse project files for your Android application, together with the native extension code within the "User Native Project Directory" you specified in your ELIPS Studio project properties for Android devices.
    Note that a new folder has been added to your project called "extensions\Android 1.6". It contains the template ".java" file for which you will need to implement the native part of the music_playback() method.
    

22. Start Eclipse, and import the generated Android project: "File" -> "import" -> "existing project into workspace", and browse to the folder you've set in the "User Native Project Directory" setting.


23. Copy the music file you want to play (for ex: openwah.mp3) in the "\res\raw" directory.



24. In the "\src" folder of your project, there is a com.openplug.elips3.extension package. Open the "*impl.java" file which is the java stub to be used for implementing the native extension method for Android.



25. In this file, you are going to implement the native version of music_playback function, and for this, to make use of the Android MediaPlayer class to play the audio file. Refer to the Android developer site for more details regarding Android libraries.


package com.openplug.elips3.extension;
import com.musicplaybacksample.MusicPlaybackSample.R;
import android.media.MediaPlayer;
class NativePlayerImpl implements NativePlayer
{
    public boolean music_playback(ASContext ctxt, ASObject thiz)
    {
        // TODO: Add your code here
        MediaPlayer mp =
            MediaPlayer.create(ElipsAndroidUtils.getContext(), R.raw.openwah);
        try {  
            mp.setVolume(1, 1);
            mp.setLooping(true);
            mp.start();
            return true;
        }
        catch (Exception e) {
            if (mp != null) {
                mp.stop();
                mp.release();
            }
            return false;
        }
    }
}

 

26. Eclipse is usually in auto-build mode, so build and generation of the apk should be done each time you modify a file. The result is a ".apk" generated in the project "\bin" folder using a temporary certificate that can be used for test purposes.
    


27. To simulate with the Android emulator (if you have created a Virtual Device, refer to prerequisites), disconnect any Android phones attached to your PC, and click "Run". The first run displays a popup, select "Android Application" button. This will start the Android emulator. Note that this process can take a while, as it runs an emulator with the complete Android OS, and is similar to booting the real phone. Note also that you may need to unlock the screen to see your app running.
    Tip: if you use "Run As", and the submenu is empty, click on your project, and do again "Run As".
    





28. To run on the device, you can install the "\bin\*.apk" application file on your Android device using adb, as described in the Android tutorial, or alternatively, attach the phone to your PC, and hit the "Run" button of Eclipse, and then select the Android device in the popup, instead of the Virtual Device.


29. Launch the application and ensure that pressing the play button actually plays the audio file. Congratulation!
30. Finally, to generate an Android binary application file with a proper certificate in Eclipse:
    • Go to "File" -> "Export...".
    • Choose "Android"->"Export Android Application".

      

    • Select the project you want to export.

      

    • Use the certificate you created in ELIPS Studio and fill in the keystore path, keystore password, key and key password.

      

      

    • Then choose the destination folder.

      

Conclusion

With this tutorial, you have learned how to create native extensions within your ELIPS Studio project and how to implement them natively on iPhone and Android. You can use the same mechanism in order to access any native function and benefit from each platform unique features without limit.
This allows you to do virtually anything...

Enjoy the freedom!