================================================================ RELEASE NOTE: Series 60 Chinese MIDP SDK 2.0 for Symbian OS (30.11.2004) ================================================================ This is Series 60 Chinese MIDP SDK v2.0 for Symbian OS. It supports Series 60 Developer Platform 2.0 and is especially meant to be used in Chinese application development for Nokia 6600. Supported Platforms =================== The emulator has been tested on (English and Chinese Simplified) Windows 2000(SP3) and Windows XP(SP1). These are currently the only supported operating systems, others may work, but have not been used in testing. The following tools can be used: - Borland JBuilder (tested with JBuilder 8 + MobileSet 3.01) - J2ME(TM) Wireless Toolkit (tested with version 2.0) - Sun ONE Studio 4, Mobile edition Update 1 - Nokia Developer's Suite for J2ME(TM) (tested with version 2.0) - Command line development tools Usage From JBuilder 8 ===================== Installation and configuration ------------------------------ Follow the instructions of MobileSet Guide under JBuilder's help menu to configure this emulator as a JDK to be used in application development. JBuilder automatically recognize this emulator as a UEI emulator. Note that the emulator must be installed into a directory, where the full absolute directory name does NOT contain spaces. Development ----------- This emulator is only able to run applications packaged into a MIDlet Suite as specified in MIDP specification. This means that both a JAD file (Java Application Descriptor) and a JAR file must be created before the application can be run. For general instructions on creating MIDlet Suites see the MobileSet Guide in JBuilder 8. Users of JBuilder Personal Edition can, for instance, manually create the JAR and JAD files with the tools found in J2SE(TM) SDK and MIDP SDK, or use the Nokia Developer's Suite for J2ME(TM) to create those files. In addition you need to make sure the following is done before attempting to run the application: (1) Select Project->Project Properties...->Paths (tab) and select the correct JDK to be used for building and running the application. If you change this setting, you need to close the window by pressing OK before proceeding to the next step. (2) Select Project->Project Properties...->Run(tab)->MIDlet(tab) and select the created JAD file as the 'entry point' for the application. (3) In the same window, add optional command line options, such as tracing flags into the "Emulator parameters" field if necessary and accept the settings by pressing OK. If you are using Professional or Enterprise Edition of JBuilder and the Archive builder (JAR tool) that comes with those, the JAR file is automatically updated in the build process. With JBuilder Personal Edition 8 and Nokia Developer's Suite, it is important to 'Recreate' the JAD and JAR files after building and before running the application. Otherwise the emulator will run the old version of these files instead of using the newly compiled classes. Usage from J2ME(TM) Wireless Toolkit 2.0 ======================================== Installation and configuration ------------------------------ The emulator will appear in Wireless Toolkit's device list if it has been installed into directory \wtklib\devices. Note that the emulator must be installed into a directory, where the full absolute directory name does NOT contain spaces. Development ----------- About Preferences window: The emulator uses and supports the default Preferences UI in J2ME WTK with the following exceptions: - The Security server address and port settings have no effect, since HTTPS is not supported. - Http-proxy settings are not supported. - The heap size setting has no effect, since the device has a dynamically growing Java heap. About Utilities window: The clean database utility in J2MEWTK has no effect with this emulator. The only way to clean up the RMS database of the emulator is to manually delete the file rms.db from emulator's C-drive. This directory is located in \bin\\epoc32\wins\c\tmp\midp. Usage from Sun ONE Studio 4, Mobile edition Update 1 ==================================================== Installation and configuration ------------------------------ The emulator integrates into Sun ONE Studio either via J2ME Wireless Toolkit or via UEI. WTK must be installed to integrate with SUN ONE Studio and the emulator directory must be installed into directory \wtklib\devices. Via UEI, emulator must be configured as a new emulator. Please refer Sun ONE Studio Help. Note that the emulator must be installed into a directory, where the full absolute directory name does NOT contain spaces. Usage from command line: ======================== \bin\emulator -help Syntax: emulator [arguments] Arguments are: -classpath, -cp The classpath for the VM -D Property definitions -version Display version information about the emulator -help Display list of valid arguments -Xverbose[:allocation | gc | gcverbose | class | classverbose | verifier | stackmaps | bytecodes | methods | methodsverbose | frames | stackchunks | exceptions | events | threading | monitors | networking | all ] Enable verbose output -Xquery Query options -Xdebug Use a remote debugger -Xrunjdwp:[transport=,address=
,server=[y|n], suspend=[y|n] Debugging options. -Xdescriptor: The JAD file to be executed -Xheapsize: (e.g. 65536 or 128k or 1M) specifies the VM heapsize (overrides default value) E.g. (the following as a one line command) c:\Series60_MIDP_SDK_2_0_for_SymbianOS\bin\emulator -Xdevice:Series60_MIDP_SDK_2_0_for_SymbianOS -Xdescriptor:c:\myprojects\mymidlet.jad Other notes about the emulator ============================== WM API ------ This emulator supports Wireless Messaging API (WMA) specification 1.1 even the javadoc version is 1.0 (no new classes since 1.0). Protection Domain ----------------- In order to simulate different Protection Domains, use the preferencies tool \bin\prefs.exe By default the Protection Domain is Untrusted. See "Security for MIDP Application" in MIDP2.0 document for more detailed information. JAD/JAR checking ---------------- Real devices will perform MIDlet installation time checks to ensure consistency between the JAD file and the JAR file. Especially the manifest file in JAR needs to match with the JAD file as specified in Mobile Information Device Profile (MIDP) Specification, Version 2.0 (http://jcp.org/aboutJava/communityprocess/final/jsr118/index.html). This emulator does not perform these checks. Ensure, that JAD and JAR file contents is in line with the spec. Otherwise a MIDlet may run in the emulator but fail to install into a real device. MIDlet size limitations ----------------------- The emulator does not emulate the real memory size of a device. It should be kept in mind that there are limitations in real devices for maximum size of a MIDlet suite. This emulator does not limit the amount of RMS data, that a MIDlet suite can store. However, real devices, may have some device specific limitation for RMS data size. MIDP UI components ------------------ Command mapping: -The implementation will add an Exit command into Options menu if one is not provided by the application. For this reason it is sometimes possible to see two Exit commands in Options menu. This happens if the application uses Command types incorrectly, i.e. has not used the proper Command.EXIT type for the Exit command. Form: - Commands "Copy text" and "Find in page" get automatically added into the displayable. Button mappings --------------- Basic navigation: Navigating the MIDP lcdui high level UI elements is done with the navigation keys (up, down, left, right). Pressing OK can be used as SELECT. Lcdui commands get mapped to the two soft buttons below the screen. Game action mapping: - Key 2 and key 'up' -> UP - Key 8 and key 'down' -> DOWN - Key 4 and key 'left' -> LEFT - Key 6 and key 'right' -> RIGHT - Key 5 and key 'OK' -> FIRE - Key 7 -> GAME_A - Key 9 -> GAME_B - Key * -> GAME_C - Key # -> GAME_D RMS Database ------------ RMS database has to be deleted manually when midlet is not installed. RMS database file is rms.db, this directory is located in \bin\\epoc32\wins\c\tmp\midp. Common problems and solutions ----------------------------- o If during debugging the IDE/debugger seems to get frozen or unresponsive - It often helps to switch to the emulator window and press a long press on the menu key followed by selecting the MIDlet process. This will switch the MIDlet into foreground and ensure it will get executed in the emulator. This symptom mostly happens during MIDlet startup and may be related to switching between Displayables. o Error message: Classpath is not set. Defaulting to "." - Check the command line parameters. This error message is sometimes given when there are unrecognized parameters on the command line. - Check that emulator installation directory does not contain spaces. o If emulator doesn't start - check JDK path from \bin emulator.cfg file. Spaces are not allowed in JDK path. - Solving: reinstall your JDK to the folder without spaces and change paths in emulator.cfg file. - Please make sure that you have JAD and JAR files. I.e. emulator can't be started with pure MIDlet class. Bluetooth --------- The emulator supports Java Bluetooth API (JSR-82) using Bluetooth PC Card installed as a serial port device or Bluetooth modules connected using RS-232 interface. Emulator supports H4 and BCSP protocols for communication with the Bluetooth hardware. Protocol used can be specified in \bin\Series60_MIDP_SDK_2_0_for_SymbianOS_chinese\epoc32\wins\c\system \data\bt.esk by modifying hcidllfilename line to contain either hci.dll (default, BCSP) or hci_h4.dll (H4). Also, the port number should be set to zero based port number (ie. for Bluetooth device connected to COM4, specify port=3) Known bugs and features ----------------------- - This emulator does not properly support the -classpath command line flag. MIDP libraries are inbuilt into the emulator and location of the application JAR is determined using the JAD file. - This emulator does not support -D flags i.e. system properties. - This emulator does not emulate the real memory size of a device - Neither Enter key, nor Space bar work as Select key. One must press the OK button (selection key) or choose select from options list (under left soft key). - Push, datagram and server socket features can be used only with installed midlets. Midlets can be installed as follows: 1. Copy midlet (.jad and .jar) to path: \bin\Series60_MIDP_SDK_2_0_for_SymbianOS_chinese\epoc32\wins \c\nokia\installs 2. Start \bin\Series60_MIDP_SDK_2_0_for_SymbianOS_chinese\epoc32\release\ wins\udeb\epoc.exe 3. Run application manager from configuration menu and select the midlet to be installed. - This version does not support ringing tones (*.rng), AMR, 3GP and MP3 formats. - MIDI is supported by native Windows MIDI. - WMA implementation does not actually send any messages into network. Instead, it writes messages into \bin\Series60_MIDP_SDK_2_0_for_SymbianOS_chinese\epoc32\wins \c\smsout folder. Incoming messages maybe place in smsin folder, e.g. by moving files from smsout folder to smsin, which appears as emulator receiving it's own sent messages. --------------------------------------------------------------------------- The phone simulation used in this SDK is designed to show how applications may appear on J2ME(TM) enabled mobile phones. It simulates the look&feel and behavior of the Nokia Series 60 based phones as faithfully as possible but there may be some differences between this simulator and the final products. Copyright (c) 2001-2004 Nokia Corporation. All rights reserved. Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation. Includes Java(TM) technology from Sun Microsystems, Inc. Portions of this Software are Copyright by Sun Microsystems, Inc. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other product and company names mentioned herein may be trademarks or trade names of their respective owners.