This API is used to write stub applications for S60 based phones.
The stub application is a specialized host application visible in Shell UI with its own icons and caption texts, uses the private SWF attached to the stub and has the assigned set of platform security capabilities. This will provide Flash content authors to give application view to the users. For example, a Flash content author can develop a Flash game and attach the stub application to the content.
FlashUIConfig defined in flash_ui.h has to be used to configure
the application into stub mode. The FlashUIConfig.iIsStubApp member variable
has to be set to ETrue for the stub application.
FlashUIConfig config; config.iIsMMI = EFalse; config.iIsStubApp = ETrue; //This should be ETrue for Stub config.iContentFileName.Copy(KStubFlashContent); config.iContentChecksum = KContentChecksum; config.iExtensions = NULL;
FlashUIConfig defined in flash_ui.h has to be used to pass the SWF file to the stub application. This SWF has to be in private data caged area to protect from accidental deletion or replacing by malicious SWF content.
const TUid KUidFlashStubApp = { 0x1027377B };
_LIT(KStubFlashContent, "\\Private\\1027377B \\stub.swf");
const TUint32 KContentChecksum = 0;
FlashUIConfig config;
config.iIsMMI = EFalse;
config.iIsStubApp = ETrue;
config.iContentFileName.Copy(KStubFlashContent);
config.iContentChecksum = KContentChecksum;
config.iExtensions = NULL;
Flash Stub applications require higher allocation of heap and stack size. epocheapsize sets
the static and dynamic size for the heap. epocstacksize sets
the stack size. Here the example value is set to 1MB for static heap and 16MB
for dynamic heap, 20KB set for stack size. Flash Player paints red mark in
display area when it does not have enough heap configured to decode image
embedded in the flash content, in this case increase epocheapsize values.
Capability of the stub application depends on the flash content. A flash game
not using network or any device services can have NULL capability. If swf
content uses network then it needs NetworkServices capability.
epocheapsize 1048576 16777216 epocstacksize 0x5000
The following example code demonstrates how to write a stub application:
#include "stub.h"
#include "flash_ui.h"
////////////////////////////////////////////////////////////////////////////////
// App initialization functions
////////////////////////////////////////////////////////////////////////////////
#include <eikstart.h>
#include <aknnotewrappers.h>
LOCAL_C CApaApplication* NewApplication( )
{
return new(ELeave) CFlashStubApplication;
}
GLDEF_C TInt E32Main()
{
return EikStart::RunApplication(NewApplication);
}
CFlashStubApplication::~CFlashStubApplication()
{
if (iFlashLibrary.Handle())
{
iFlashLibrary.Close();
}
}
const TUid KUidFlashStubApp = { 0x101FD69F};
_LIT(KStubFlashContent, "\\private\\101FD69F\\stub.swf");
TUid CFlashStubApplication::AppDllUid() const
{
return KUidFlashStubApp;
}
CApaDocument* CFlashStubApplication::CreateDocumentL()
{
FlashUIConfig config;
config.iIsMMI = EFalse;
config.iIsStubApp = ETrue;
config.iContentFileName.Copy(KStubFlashContent);
config.iContentChecksum = 0;
config.iExtensions = NULL;
if(!FlashStubsSupported())
{
User::Leave(KErrNotSupported);
}
return CreateFlashDocumentL(iFlashLibrary, this, config);
}
#include <aknapp.h>
#include <akndoc.h>
class CFlashStubApplication : public CAknApplication
{
public:
~CFlashStubApplication();
TUid AppDllUid() const;
protected:
CApaDocument* CreateDocumentL();
RLibrary iFlashLibrary;
};
A resource file has to be written to define the caption and icon for the stub application. Stub writers can write LOC files for all localizable resource string and provide resource Ids in the RSS file.
Example Stub.rss file:
NAME STUB // 4 letter ID
RESOURCE RSS_SIGNATURE
{
}
RESOURCE TBUF r_default_document_name
{
buf="SUDO";
}
RESOURCE EIK_APP_INFO
{
menubar = r_stub_menubar;
cba = R_AVKON_SOFTKEYS_OPTIONS_EXIT;
}
RESOURCE MENU_BAR r_stub_menubar
{
titles =
{
MENU_TITLE { menu_pane = r_stub_menu; }
};
}
RESOURCE MENU_PANE r_stub_menu
{
items =
{
MENU_ITEM
{
command = EAknSoftkeyExit;
txt = "Exit"; //.loc file for localization
}
};
}
RESOURCE LOCALISABLE_APP_INFO r_stub_localisable_app_info
{
short_caption = qtn_apps_flite_grid;
caption_and_icon =
CAPTION_AND_ICON_INFO
{
caption = "stub"; //qtn_apps_flite_list;
number_of_icons = 1; // each icon must be a bitmap/mask pair
icon_file = "z:\\resource\\apps\\stub_1.mbm";
};
}
Example Stub_reg.rss for registering stub application:
// INCLUDES
#include <appinfo.rh>
#include <stub.rsg> //rsg file for the stub application
#include <data_caging_paths_strings.hrh>
UID2 KUidAppRegistrationResourceFile
UID3 0x1027377B //UID of Stub application
//RESOURCE DEFINITIONS
// ----------------------------------------------------------------------//
// APP_REGISTRATION_INFO
// Registration resource for
//
// ----------------------------------------------------------------------//
RESOURCE APP_REGISTRATION_INFO
{
app_file = "stub";
localisable_resource_file = APP_RESOURCE_DIR"\\stub";
localisable_resource_id = R_STUB_LOCALISABLE_APP_INFO;
embeddability=KAppNotEmbeddable;
hidden=KAppNotHidden;
newfile=KAppDoesNotSupportNewFile;
datatype_list=
{
DATATYPE
{
priority=EDataTypePriorityNormal;
}
};
}
// End of File
A PKG file can be written to create SIS package for the stub application. Here application writer can mention dependency on the Flash Lite application. This will make installation of stub application only on the mobile devices having Flash Lite installed. This PKG file can be used to create SIS package using the makesis tool provided with S60 SDK.
Example Stub.pkg file:
; Installation file for Flash Lite Stub application
;
;Languages - UK English, US English;EN;
; Localised Vendor name
%{"Vendor-EN"}
; Unique Vendor name
:"Vendor"
; UID is the app's UID
;
#{"Stub"},(0x1027377B),1,0,0
;
; Depends on Flash Lite 2.x being installed
(0x101FD693), 2, 0, 0, {"Flash Lite"}
; Flash stub application
;
"\epoc32\release\armv5\urel\Stub.exe" -"!:\sys\bin\Stub.exe"
"\epoc32\data\z\resource\apps\Stub.rsc" -"!:\resource\apps\Stub.rsc"
"\epoc32\data\z\resource\apps\Stub.mif" -"!:\resource\apps\Stub.mif"
"\epoc32\data\z\private\10003a3f\apps\Stub_reg.rsc" -"!:\private\10003a3f\import\apps\Stub_reg.rsc"
Example Stub.mmp file:
TARGET Stub.exe
TARGETTYPE exe
UID 0x100039CE 0x1027377B
CAPABILITY NULL
SOURCEPATH ..\src
SOURCE stub.cpp
START RESOURCE ..\data\stub.rss
HEADER
TARGET stub.rsc
TARGETPATH APP_RESOURCE_DIR
LANG SC
END
START RESOURCE ..\data\stub_reg.rss
TARGET stub_reg.rsc
TARGETPATH \private\10003a3f\apps
END
USERINCLUDE ..\inc
USERINCLUDE ..\..\inc
SYSTEMINCLUDE \epoc32\include
LIBRARY euser.lib
LIBRARY apparc.lib
LIBRARY eikcore.lib
LIBRARY avkon.lib
LIBRARY centralrepository.lib
epocstacksize 0x5000
epocheapsize 262144 16777216
Flash Lite is an Adobe product. All S60 phones may not have Flash Lite installed. flash2ui.dll should be present in the phone. If this DLL is not present in the phone, the stub application will exit. The stub application writer can add dependency to Flash Lite in PKG file during installation of the stub application. Flash Player Engine handles the errors. It uses Symbian Leave mechanism for any critical errors.
RAM consumption of stub application depends on the flash content. There is a maximum limit on RAM to be allocated for the stub application. It is not possible to allocate more memory for flash content, the stub application will exit with Out of Memory message.
There is no extension to API possible.