The purpose of this API is to provide an interface to play the flash content. This API provides ability to write a lightweight 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, e.g. a Flash content author can develop a Flash game and attach the stub application to this game.
| API category | public |
| API type | c++ |
| Existed since | Legacy S60 5.0 |
| Location | /sf/mw/appsupport/appsupport_pub/flash_viewer_framework_api
|
| Buildfiles | /sf/mw/appsupport/appsupport_pub/flash_viewer_framework_api/group/bld.inf
|
Flash Viewer Framework API provides the ability to write lightweight stub applications for Symbian OS executing flash content. Flash Player Engine handles SWF format. 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 the application view to the users, e.g. a Flash content author can develop a Flash game and attach the stub application to this game.
This API is a Framework API provided by Flash Viewer Framework. It provides uniform UI options for executing flash content in S60 based phones.
This API is a method call invoking Flash Player engine. This uses application thread for rendering flash content. There are no extra threads spawned.
Flash Player Engine handles all the error conditions. It uses Symbian Leave mechanism for any critical errors. The stub application does not have control over the flash errors. There is no communication between the stub application and Flash Player Engine. The stub application is a lightweight application. Flash Player supports only SWF formats. It does not support FLA format. It handles OMA DRM v1.0 protected SWF content. Flash play-out is done in the application thread. There are no extra threads spawned.
The use case of Flash Viewer Framework API is to develop stub application for S60 based phones.
| Classes | Files |
|---|---|
| No classes | /epoc32/include/mw/flash_ui.h
|
This API provides single method CreateFlashDocumentL .
This method needs the FlashUIConfig structure to be filled. The FlashUIConfig
structure contains parameters to configure Flash Player Engine to stub application
mode. The CreateFlashDocumentL method will leave if the Flash
Lite library not installed in the device.
| RLibrary& aLibrary | Output variable to be passed to the method. When Flash Lite library
is loaded it returns an instance of the library. |
| CEikApplication* aApp | Input variable. Pointer to the application object needed to be passed. |
| const FlashUIConfig& aUIConfig | FlashUIConfig structure to be filled and passed to this method. The
FlashUIConfig structure contains configuration information for the stub application. |
|
Player. When error occurs this method will leave.
| TBool iIsMMI | This variable should be set to |
is set as ETrue then MMI feature will be enabled for the
stub application.
ETrue . IF this
variable is set to EFalse then the application is assumed
to be the host application. Flash Viewer application, a host application is
already available as part of the Flash Lite installation.
is supported.
checksum will not be verified. CRC algorithm is used to verify checksum.
set to NULL.
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; config.iReserved1 = NULL; config.iReserved2 = 0;
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;
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.
| DLL | Dynamic Link Library |
| OMA | Open Mobile Alliance |
| DRM | Digital Rights Management |
| OS | Operating system |
| CRC | Cyclic Redundancy Check. Algorithm used to calculate checksum. |
| MMI | Man Machine Interface |
| AS, ActionScript | ActionScript is the Flash scripting language that lets
you add complex interactivity, playback control, and data display to a Flash document. You can add ActionScript within the Flash authoring environment using the Actions panel or create external ActionScript files using an external edit |
| Flash | Flash is a time line based scripted animation programming
environment. The Flash authoring tool allows you to create anything from a simple animation to a complex interactive web application, such as an online store. You can make your Flash applications media rich by adding pictures, sound, and video. Flash includes many features that make it powerful but easy to use, such as drag-and-drop user interface components, built-in behaviors that add ActionScript to your document, and special effects that you can add to objects. |
| Flash Lite | Flash Lite is a profile derived for mobile environments from desktop
(full) players. Roughly speaking : Flash Lite 1.1 Player equals to Desktop Flash Player 4 with mobile extensions; Flash Lite 2 equals Desktop Flash Player 7 with mobile extensions; Flash Lite 2.1 equals Desktop Flash Player 7 with mobile extensions; Flash Lite 3.0 equals Desktop Flash Player 9 only AS2 with mobile extensions. |
| SWF | Adobe Flash file format. Flash content file created by Flash authoring
tool. |
| Flash MMI | MMI feature allows flash content to interact with mobile device services.
Symbian application developers to develop Flash MMI plug-ins based on Adobe's Flash Lite MMI specification. |
| Adobe Flash Lite web page |