This API is used to write stub applications for Symbian devices.
Stub application
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.
Using FlashUIConfig structure to run Flash Lite application in stub
mode
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;
config.iReserved1 = NULL;
config.iReserved2 = 0;
Related APIs
Passing SWF for stub application
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;
config.iReserved1 = NULL;
config.iReserved2 = 0;
MMP file
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
Related APIs
-
epocheapsize
-
epocstacksize
Writing source for stub application
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);
}
Writing header for stub application
#include <aknapp.h>
#include <akndoc.h>
class CFlashStubApplication : public CAknApplication
{
public:
~CFlashStubApplication();
TUid AppDllUid() const;
protected:
CApaDocument* CreateDocumentL();
RLibrary iFlashLibrary;
};
Writing resource file
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";
};
}
Writing registration file
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
Writing PKG 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 Symbian 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 MMP file
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
Error handling
Flash Lite is an Adobe product. All Symbian devices 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.