Tutorial: Flash and C++ Native Extension

Last week I decided to look into building a native extension for AIR and was very surprised by the lack of quality resources and tutorials for doing so. I was able to find examples for Android using Java and for iOS using Objective-C, but pretty much nothing for a standard Windows C++ project. I was eventually able to get things up and running by piecing together bits of information from various sources, but I thought I'd take the time to write a step-by-step tutorial on how to do this so that perhaps others will have an easier time. In this tutorial you will create a native extension that simply adds two numbers together and returns the sum.

I'll start with a warning: this tutorial is not for the absolute beginner. You will need the AIR/Flex SDK, Microsoft Visual Studio, familiarity with C++ coding and be comfortable creating packages via the command line. Also, while I'm comfortable with Flash and ActionScript, I am definitely not an authority on C/C++ so there may be other (better) ways to do some things. Of course, if you happen to be an authority on that stuff, please feel free to suggest improvements! Ok, with the initial disclaimer out of the way, let's go ahead and get our hands dirty!

Setting up the C++ project

To begin, you'll need to have Microsoft Visual C++ 2010; and yes, the free Express edition is just fine. Once you've got that installed (and any necessary updates) go ahead and open it up and start a new project. We want to create a Win32 project so select that and give it the name NativeAdd.

Select Next and on the following screen, under Application Type, choose DLL (Dynamic-Link Library) and click Finish.

Great! The C++ project has been created! The next step is to make a few changes to the code; open up dllmain.cpp and the top of the file remove the following line:

#include "stdafx.h"

and replace it with this:

#include <Windows.h>

After that, let's go to the DllMain function and remove the entire switch statement so that the only code left in the function is: return TRUE;

The dllmain.cpp file should now look like this:

#include <Windows.h>

BOOL APIENTRY DllMain( HMODULE hModule,
                       DWORD  ul_reason_for_call,
                       LPVOID lpReserved )
{
    return TRUE;
}

Now turn your attention to NativeAdd.cpp and remove the line: #include "stdafx.h"

The next thing we'll do is get rid of the extra files automatically added to the project by Visual Studio. In the solution explorer, open the Header Files folder and right click the stdafx.h file and select Remove. Go ahead and just click remove again if you get a popup box. Do the same to targetver.h and also stdafx.cpp in the Source Files folder.

The next step is to add a few files. First, we'll add NativeAdd.h to the Header Files folder. To do so, right click the Header Files folder and select Add > New Item. Select Header File from the list and name it NativeAdd.h.

Now we'll grab some necessary files from the Flex SDK and add them to our project. Navigate to the Flex SDK directory and enter the include directory. You'll want to copy the FlashRuntimeExtensions.h file from there. Go back into Visual Studio and right click the Header Files folder, select Add > Existing Item. When the file selection dialog comes up, paste the FlashRuntimeExtensions.h and then select it.

We've got one more file to grab from the Flex SDK so go back to the root folder of the Flex SDK. Navigate to lib/win and copy the FlashRuntimeExtensions.lib file. Right click the NativeAdd project in the solution explorer and select Add > Existing Item and again paste the file in the file selection dialog box and select it to add it to the project. If you've followed along your solution explorer should look like the image below.

We've got just one more thing to take care of before getting into the code. Because we removed the stdafx files, we need to tell the compiler not to look for them. To do this, right click the project file in the solution explorer. Select Properties to bring up the dialog box. Choose Configuration Properties > C/C++ > Precompiled Headers. At the top of the dialog box, change Configuration to All Configurations. Now, in the right-most pane, change the Precompiled Header option to Not Using Precompiled Headers. Use the image below as a guide if you need it.

Pages: 1 2 3 4 5

Bookmark and Share

35 Responses to “Tutorial: Flash and C++ Native Extension”

  1. Impressive publish! STICK WITH IT!

  2. Khan says:

    Excellent tips. Good tutorial for c++.

  3. Tomasz Dysinski says:

    Excellent and thorough!

    I have a comment about the following command line:

    adt -package -target ane NativeAdd.ane extfiles/extdesc.xml -swc extfiles/com.yourname.NativeAdd.swc
    -platform Windows-x86 -C extfiles NativeAdd.dll library.swf

    You left the namespace in extfiles/com.yourname.NativeAdd.swc. I couldn’t get it to work until I removed the namespace part, but then again, I wrote a BAT file to run this from the bin folder instead of the extfiles folder in the flex SDK bin folder (more typing, but less chance of misplacing files).

    Anyways, thanks again for taking the time to write this.

  4. Rhuno says:

    There is a lot going on in this tutorial. I do plan on eventually trying to make a video tutorial for this as it may be easier to follow.

  5. Erik Forsstrom says:

    Thank you so much for taking your time and writing this great tutorial!

    If you have plans to create a .bat file for the AS3 side, this acompc compiler option helps alot
    -directory=true -output=destination_directory
    This saves you the step of unpacking the library.swf from the .swc
    Run the acompc twice, one for the .swc and one for the .swf

  6. Mike says:

    Great tutorial.

    Thank you for your time to put this toghter. Bookmarked.

    Cheers Mike.

  7. BunbunManJu says:

    Hi, I have this error when I tried to package the ane file. It say ‘java’ is not recognised as an internal or external command. Do you know how I can resolve this?

  8. BunbunManJu says:

    Hi, I had solved the previous error. But now, I have another one.
    _ctx = ExtensionContext.createExtensionContext(); keep returning null. Please help. Q.Q

  9. BunbunManJu says:

    Hi again, I have gotten pass the above error too and now when I build the flash develop project, it did trace out 10 in the output window, the thing is I got a error while loading initial content in the AIR debug launcher. I have totally no idea what is wrong as I followed your tutorial step by step. Please help me. O ya, one thing, I can’t seem to put at the end of my NativeAdd.cpp. it gives me a syntax error. Is it because of this?

  10. BunbunManJu says:

    I tried the extension in flash pro and it keep spitting the error that _ctx is null even though I had call the constructor. O dear… Please help!

  11. Rhuno says:

    I haven’t tried this with Flash Pro, but I’m guessing there is some way you need to tell it you’re using a native extension.

  12. neelam ojha says:

    great article. keep it up.thanks

  13. chenze says:

    It ‘s very technical! It ‘s helpful for me, thanks a lot.

  14. Luis Furtado says:

    Just amazing! Thank very much!

  15. Nemis says:

    Thanks!

  16. John says:

    Great tutorial! Everything’s going real well so far, except I have one question. On this page, there’s the following phrase:

    Now rename the extracted to folder to NativeAdd.ane; you can delete the NativeAdd.zip file leaving
    only the NativeAdd.ane folder. We’re almost done, I promise!

    I’m using WinRAR, but I don’t think it should make that much of a difference. When I try to extract that zip file, I just get four files out of it, not another folder. When you say to rename the extracted folder to NativeAdd.ane, what do you mean? It sounds like you mean to put these four files into a folder, then rename that folder. But on Windows, this just changes the name of the folder; it doesn’t give you a real ane file back.

  17. Rhuno says:

    John, that’s correct. If WinRAR gives you the four files, you just need to put them in a folder and name that folder NativeAdd.ane. I realize this just changes the name of the folder and does not give you a real ane file, but that’s just the way the debugging works. Wonky, eh?

  18. Sam says:

    Thanks, but the info provided is incomplete. There’s no info about how to *adapt* the example for an *existing* AIR project as this is what all we want, NOT just run this simplistic “example”.
    There is missing information, like:
    1. My AIR project is on another folder. Should I just copy the airapp.as file to c:\com\username\airapp ?
    2. My AIR package doesn’t have any folders (like package com.username), should I move and rebuild the whole project somewhere else and add this, or not?
    3. Should I built the whole project in c:\com\username\airapp instead?

  19. Rhuno says:

    Sam, the last page here describes how to use the native extension within a project. It doesn’t matter where your AIR project is because the ANE is self-contained. To use a native extension with any project, new or existing, all you need to do is copy the ANE over and make sure it is properly added to the project.

  20. Sam says:

    Also no matter what I’ve tried, I get the error: Could not find source for class com.username.

  21. Sam says:

    Just saw your post, the problem is I cannot get passed the acompc on page 3. I get the above error.

  22. Rhuno says:

    The error means the compiler can’t find your classes. Make sure the source path is set correctly and also the include-classes. Note that you need to include each file name, it won’t work if you just specify a folder.

  23. Hassan says:

    Hi Rhuno,
    I just want to say many thanks for taking time to explain all steps required to build windows ANE.

  24. Zain says:

    i got error when run the adt command: “output file is not writable”. it’s might because something about win 8 security. Then i try change the output location to drive D, and it work well.

    the other error i got is about jre installation for Flash Develop, but it could be solved after uninstalling the older version of jre..

    It’s very good tutorial, easy to understand and follow. Very deep and technical. i tried and succeed.
    i love it. thanks, for sharing :)

  25. Dave Dyer says:

    Kudos. Your ANE tutorial got me over the hump.

  26. parmar says:

    Hello Sir,

    Thanks Sir, No word for this tutorial.it was great.
    Sir I am Stuck with how to create a dll using String data type . I am also new in C++ .
    what you have used that is int data type.
    can u help me in this.
    Your help is solicited.

    Regards,
    Parmar

  27. parmar says:

    Hi,

    Please help me to create ANE using string data type.

    Regards,
    Parmar

  28. parmar says:

    Hi,
    Still waiting , please help me to create ANE with string Manipulation …

    Regards,
    Parmar

  29. Rhuno says:

    Parmar, strings are handled in a similar manner to other data types. You need to use the FREGetObjectAsUTF8 and FRENewObjectFromUTF8 functions to get/set them. In the flex sdk, go to the include directory and look at the FlashRuntimeExtensions.h. That has all the native functions available to you and is heavily commented.

  30. parmar says:

    Thanks Rhuno…

    Actually for me const uint8_t* … these kind of data types are new.
    So I am feeling tough to manipulate these kind of data type in simple int , string data types,thatswhy I was asking for any string manipulated dummy app of any example to do that.

    I will try to understand FlashRuntimeExtensions.h. hope i will be able to do string manipulations.

    Once again thanks a lot for your support.
    Thanks

    Regards,
    Vishal Parmar

  31. Zain says:

    is it possible to hold instance of a variable in the C dll with ANE?
    So several FREObject function could use it.

  32. kleone says:

    Perfect tutorial. Thank you!

  33. mehdadoo says:

    Man your article was great! Thank you so much.

  34. SourceSkyBoxer says:

    I have problem with error include :( I have added h and lib why does it not work :(

  35. Boris says:

    Your article was beautiful

Leave a Reply

Subscribe to RSS feed FGS5 Badge