Invoking ICU from Adobe AIR Applications

This article was originally written in English. Text in other languages was provided by machine translation.

Adobe Flash and AIR are ubiquitous platforms to develop rich internet applications. Flash is used for browser based applications and AIR is used for developing native platform applications. Both platforms have considerable support for globalization. Globalization enablement features like locale aware formatting/parsing, collation, case transforms, localization and multi-lingual text rendering are supported by both these platforms. But some more globalization features like text normalization, transliteration, Unicode character properties, encoding conversions, charset detections, Unicode string utilities etc are still missing in the Adobe AIR and Flash platforms. One of the primary reasons for not adding all these features inside the Adobe runtime platforms is the size of the software.

To overcome the size limitation issue, Adobe AIR and Flash can invoke the services of external dynamic libraries through ActionScript. There are some well known external libraries which have rich globalization support like ICU, GNU glib, Verisign IDN library to name a few. Fortunately the upcoming Adobe AIR 3.0 (now available as Adobe pre-release) has a wonderful feature called ActionScript native extensions, which is about ActionScript programming interface for a native code library like MS Windows DLL, Os X FrameWork, Android JAR or shared library or iOS static library. Please see Adobe AIR3 beta site on how to download and take part in the Adobe AIR pre-release. Please make a note that this native extensions feature is available _only_ in Adobe AIR platform, not in the Flash platform.

In this blog, I demonstrate a sample (Download air_icu ) application to invoke ICU from an Adobe AIR application on Windows platform. Readers are reminded that this is only illustration sample software and by no means production quality software. Hence readers must exhibit discretion in using this software as it is. The sample illustrates ICU word breaking, sentence breaking, utf-conversion and Unicode character property verification.

You will need the following software to build an ICU extension for AIR platform.

1         Building ICU extension for Adobe AIR

Adobe AIR t native extensions, also known as ‘ane’ or ‘ANE’ files are archived packages. These consist of

  • ActionScript wrapper classes calling into external DLLs
  • The external DLLs
  • XML file describing details of external DLLs

The archived ANE files are used just like SWC libraries in integrating into an AIR application. In other words, ANE file is a library and it has public ActionScript APIs.

Covering all details about the ActionScript extension is too much for this blog article, but I will explain the steps to build this sample and run. Below are the sequential steps and commands.

1.1       Building Windows AIR ICU Extension DLL

1)      The AirIcuExtensionWin folder has the Visual studio solution ‘AirIcuExtension.sln’. Open this in MS VS2010.

2)      The file AIRIcuExtension.cpp has the necessary code needed to interface with Adobe AIR 3 beta 2. It also has the wrapper routines calling ICU C functions.

3)      This is a DLL project and the build output is AirIcuExtension.dll

1.2       Building ActionScript Library

1)      Build the actionscript library using the below command.

C:Flex4.5.1bincompc.exe -source-path src -include-classes com.adobe.extensions.AirIcuExtension  -external-library-path C:air3_beta2frameworkslibsairairglobal.swc -output binAirIcuExtension.swc

The file in the folder srccomadobeextensions has the public class AirIcuExtension which calls the ICU routines. In this sample, calling ICU sentence breaker, word breaker, normalizer, utf-conversion and Unicode character property have been illustrated.

1.3       Packaging ActionScript native extension

Open the binAirIcuExtension.swc is a zipped archive. Open it using WinRAR or WinZip program and extract the library.swf file in the swc package into the AirIcuExtension/bin folder.

The folder srcresources contains file extension.xml, AirIcuExtension.dll and ICU dlls icudt48.dll, icuuc48.dll, icuio48.dll and icuin48.dll. The file external.xml defines the external library details to AIR runtime.

For simplicity, place the AirIcuExtension.dll, ICU dlls and extension.xml files in AirIcuExtensionbin folder. All these files are packaged into a zipped archive called AiricuExtension.ane using the following command.

C:air3_beta2binadt -package -storetype pkcs12 -storepass <passwd> –keystore <AIR certificate> -tsa none -target ane AirIcuExtension.ane extension.xml -swc AirIcuExtension.swc -platform Windows-x86 library.swf AirIcuExtension.dll icudt48.dll icuin48.dll icuio48.dll icuuc48.dll

Using Adobe FlashBuilder4.x or  C:air3_beta2binadt program, one can make an AIR certificate.

The output is an archive file AirIcuExtension.ane in the AirIcuExtension/bin folder.

1.4       Building the Test program AirIcuExtensionTest.mxml

Now that we built and packaged the native extension package AiricuExtension.ane, we are readu to use this and call ICU services in a test program.

The folder AirIcuExtensionTestsrc contains the test file AirIcuExtensionTest.mxml. The descriptor file AirIcuExtensionTest-app.xml has  the details of native extension. Using the mxml compiler, AirIcuExtensionTest.swf is built as follows in AirIcuExtensionTest folder.

C:Flex4.5.1bincompc.exemxmlc +configname=air -external-library-path ..AirIcuExtensionbinAirIcuExtension.ane -output bin-debugAirIcuExtensionTest.swf — srcAirIcuExtensionTest.mxml

The output swf file AirIcuExtensionTest.swf is placed in the bin-debug folder.

1.5       Building AIR package for executing AirIcuExtensionTest

The final step is to package the above AirIcuExtensionTest .swf and AirIcuExtension.ane files into an AIR executable folder.  Execute the following command

C:air3_beta2binadt -package -XnoAneValidate -storetype pkcs12 -storepass <passwd> –keystore <AIR certificate> -tsa none -target bundle AirIcuExtensionTest.air AirIcuExtensionTest-app.xml AirIcuExtensionTest.swf -extdir ….AirIcuExtensionbin

The output of the above command is a folder AirIcuExtensionTest.air. Inside the folder, there is AirIcuExtensionTest.exe. You can execute and see the output.

2         Conclusion

The sample illustrated how to invoke ICU from ActionScript. The AIR ICU extension is easy to build using the publicly available Adobe Flex SDK and AIR3 Beta 2 SDKs. It will be much easier to do all this in the future Adobe Flash Builder IDE using GUI. The advantages of this feature are

  • AIR developers looking to develop international applications for desktop or mobile have the full power of ICU at hand. Many Unicode features, encoding conversions, IDN conversion utilities, string processing, transforms and many more international features can be easily coded.
  • The native ICU extension once built can be used any any developer as it is a library.
  • The Actionscript APIs calling ICU can be coded using the same signatures as ICU C++ API. This eliminates the learning curve.
  • Since ICU is in native code, performance is not compromised.
  • Since it is ICU, developers can expect cross-platform behavior in AIR programs.
  • Since the extension is a AIR library, ICU updates can be easily re-packaged in to the ane file.

In the future once AIR3 is released, a full fledged ICU native extension with proper API definitions will be a great globalization project.

19 thoughts on “Invoking ICU from Adobe AIR Applications”

  1. Hey,

    nice post.
    I guess this won’t work with Windows 7 64 bit obviously ^^.

    Maybe you could provide something for 64 bit as well :)


  2. Thanks for the comment.
    You are right. ICU 64bit dlls donot work in AIR 3.0. I remember I could not build the extension DLL in VS2010. AIR 3.0 does not yet support 64bit.
    We have to wait until it supports. Let us wait for post-Air3.0.


    1. Just to clarify further. I tested my extension on Win 7 64 bit laptop but used ICU 32 bit dlls.


  3. I can’t build ane using adt. I ran adt at C:air3_RC1samplesair_icuAirIcuExtensionbin after setting “set path=c:air3_RC1bin;%PATH%”. I have following files under AirIcuExtensionbin directory, but i got “system can not find the file specified.” Did I miss anything?


    09/02/2011 03:46 PM 9,216 AirIcuExtension.dll
    09/23/2011 03:16 PM 2,712 AirIcuExtension.swc
    08/19/2011 08:29 AM 514 extension.xml
    07/19/2011 04:43 PM 18,277,376 icudt48.dll
    07/19/2011 04:36 PM 1,313,792 icuin48.dll
    07/19/2011 04:42 PM 36,352 icuio48.dll
    07/19/2011 04:33 PM 1,043,456 icuuc48.dll
    09/23/2011 03:16 PM 1,867 library.swf

  4. Which file it cannot find?
    Is it adt? or the air license file?
    Are you in the directory C:air3_RC1samplesair_icuAirIcuExtensionbin when executing adt?

    There are somany files involved that you run into this error just like me when I first ran.

    1. Harish, thanks for help.
      Error message was not detail enough to see which file was missing. ADT runs okay. What is air license file? I can’t see any instruction about license file. Does it mean AIR certificate? This error is raised from adt run in step 1.3.


      1. Sorry I meant AIR certificate. You can generate air certificate using adt program.

  5. This is powerfull, I hope we will see more of ANEs in near future :)
    Nicely build on win7 x64 following steps of your research.
    I just needed to manually copy the *48.dll files into air dir, I must of have missed something regarding packaging…

    Thanks for new knowledge!

  6. For God sake, please give us an example of AIR 3.0 NativeExtension with C# .dll.

    C# is more popular in .NET framework today. I have been looking for C# sample for NativeExtension .dll from weeks and couldn’t find a single example.

    1. Hi James,
      Sorry, my example only illustrated C++/C but not C#.
      One way to try C# dll is you should invoke C# dll from a C++ dll using interop (Just google for calling C# from C++). The C++ dll must implement all AIR needed framework glue as in my sample here. This is only my guess.

  7. After I finish all steps, I got a problem when I execute the .exe file in the folder air
    It jumps a message e.g. ” can’t find the icuuc48.dll componet”
    but I have found the file “icuuc45.dll” in the folder Windows-x86~ just like the following


    Do I miss something?

    P.S. please forgive my poor English ><

  8. The icuuc48.dll must be present in the same folder as where the .exe file resides. Infact all icu dlls must be there.

    The other way is to add the icu dll folder localtion to windows path variable.

Leave a Reply

Your email address will not be published. Required fields are marked *