S60 Module Reference Release 2.0.0 final 09 Feb 2010 Nokia This is Python(R) for S60 version 2.0.0 final created by Nokia Corporation. Copyright c 2004 - 2009 Nokia Corporation. The original software, including modifications of Nokia Corporation therein, is licensed under the applicable license(s) for Python 2.5.4, unless specially indicated otherwise in the relevant source code file. You can view the entire copyright information from here pys60 copyright info.txt Abstract This document is for Python for S60 Platform (Python for S60), which simplifies application development and provides a scripting solution for the Symbian C++ APIs. CONTENTS 1 Getting Started 3 1.1 Installing Python runtime and its dependencies ...........................3 1.2 Packaging a Sample Application ...................................4 2 Operating System Services and Information 5 2.1 e32 — A Symbian OS related services package ..........................5 2.2 sysinfo — Access to system information .............................7 3 User Interface and Graphics 9 3.1 appuifw — Interface to the S60 GUI framework .........................9 3.2 globalui — Interface to the S60 global UI notifiers ....................... 26 3.3 graphics — A graphics related services package ......................... 27 3.4 camera — Interface for taking photographs and video recording ................. 33 3.5 keycapture — Interface for global capturing of key events. ................... 35 3.6 topwindow — Interface for creating windows that are shown on top of other applications. ... 36 3.7 gles — Bindings to OpenGL ES .................................. 38 3.8 glcanvas — UI Control for Displaying OpenGL ES Graphics .................. 45 3.9 sensor — Module to access the device sensors. .......................... 46 4 Audio and Communication Services 59 4.1 audio — An audio related services package ............................ 59 4.2 telephone — Telephone services ................................. 61 4.3 messaging — A messaging services package ........................... 62 4.4 inbox — Interface to device inbox ................................. 63 4.5 location — GSM location information ............................. 64 4.6 positioning — Simplified interface to the position information ................ 65 4.7 btsocket — Provides Bluetooth (BT) support .......................... 67 5 Data Management 71 5.1 contacts — A contacts related services package ......................... 71 5.2 e32calendar — Access to calendar related services ....................... 76 5.3 e32db — Interface to the Symbian native DB ........................... 80 5.4 e32dbm — DBM implemented using the Symbian native DBMS ................. 82 5.5 logs — Module to access the phone logs. ............................. 85 5.6 Acronyms and Abbreviations .................................... 87 6 scriptext - Platform Service API Usage from Python runtime 89 6.1 Overview of scriptext usage ..................................... 89 6.2 Application Manager ......................................... 96 6.3 Calendar ............................................... 105 6.4 Contacts ............................................... 128 6.5 Landmarks .............................................. 150 6.6 Location ............................................... 173 6.7 Logging ................................................ 189 i 6.8 Messaging .............................................. 201 6.9 Media Management ......................................... 217 6.10 Sensors ................................................ 222 6.11 Sys Info ................................................ 235 6.12 Appendix ............................................... 250 7 Module Repository 253 8 Extending and Embedding PyS60 257 8.1 Extending PyS60 ........................................... 257 8.2 Embedding PyS60 .......................................... 261 8.3 Porting 1.4.x to 1.9.x ......................................... 262 9 Terms and Abbreviations 265 A Known Issues 269 B Reporting Bugs 271 Module Index 273 Index 275 ii Contents 1 2 CHAPTER ONE Getting Started Thank you for installing Python for S60 package. Python for S60 is a powerful scripting language with an extensive standard library and easy-to-use APIs for S60 phone features, based on Python 2.5.4. 1.1 Installing Python runtime and its dependencies Python runtime and other libraries are available in the folder PyS60Dependencies under the installation folder. Python 2.0.0.sis - Python runtime Runtime dependent package: - pips.sis - OpenC PIPS library Optional packages/libraries: - stdioserver.sis - stdioserver to run python scripts packaged with console profile. - ssl.sis - SSL library if you need SSL support in socket module. Different variants of PythonScriptShell packages: - PythonScriptShell 2.0.0 high capas.sis - ScriptShell with high capabilities (Self-signed + Location + SwEvent + WriteDeviceData + ReadDeviceData) - PythonScriptShell 2.0.0 3 2.sis - ScriptShell with Self-signed + Location capability - PythonScriptShell 2.0.0 3 0.sis - ScriptShell with Self-signed capability set - PythonScriptShell 2.0.0 unsigned devcert.sis - ScriptShell with Developer certificate capabilities - Python 2.0.0 unsigned.sis – Unsigned Python runtime component 3 1.2 Packaging a Sample Application This section describes how to create a sis file from a Python script. 1.2.1 On a Windows host machine The following steps provide the procedure for writing and packaging a helloworld script. • Create a ”helloworld” script with the filename ”helloworld.py” containing print "Hello World!" code snippet. • Click Start - Programs - PythonForS60 2.0.0 ¿ PyS60 Application Packager, the PyS60 application packager dialog box opens. • Select the Scriptfile radio button and then, click the Browse button to select the helloworld.py script from the file Open dialog. • Click the Create button to create the sis file with the current settings. • Install the sis file helloworld v1 0 0.sis created in the source directory of ”helloworld.py” file. 1.2.2 On a Linux or Mac host machine The following steps provide the procedure for writing and packaging a helloworld script. • Create a ”helloworld” script with the filename ”helloworld.py” containing print "Hello World!" code snippet. • Using a command prompt, enter the directory which contains the ensymble.py and copy the ”helloworld.py” file here. • Execute the command "python ensymble.py py2sis helloworld.py". • The sis file would be generated in the current directory. Install this on an S60 device. • Execute "python ensymble.py py2sis --help", for more info on py2sis options. 4 Chapter 1. Getting Started CHAPTER TWO Operating System Services and Information 2.1 e32 — A Symbian OS related services package The e32 module offers Symbian OS related utilities that are not related to the UI and are not provided by the standard Python library modules. 2.1.1 Module Level Functions The following free functions - functions that do not belong to any class - are defined in the e32 module: ao_yield() Yields to the active scheduler to have ready active objects with priority above normal scheduled for running. This has the effect of flushing the eventual pending UI events. Note that the UI callback code may be run in the context of the thread that performs an ao_yield. For information on active scheduler, see S60 SDK documentation [4]. ao_sleep(interval [, callback ]) Sleeps for the given interval without blocking the active scheduler. When the optional callback is given, the call to ao_sleep returns immediately and the callback gets called after interval. See also Section 2.1.3, Ao timer Type. ao_callgate(wrapped callable) Wraps wrapped callable into returned callable object callgate that can be called in any thread. As a result of a call to callgate, wrapped callable gets called in the context of the thread that originally created the callgate. Arguments can be given to the call. This is actually a simple wrapping of the Symbian active object facility. drive_list() Returns a list of currently visible drives as a list of Unicode strings ’<driveletter>:’ file_copy(target name, source name) Copies the file source name to target name. The names must be complete paths. in_emulator() Returns True if running in an emulator, or False if running on a device. set_home_time(time) Set the device’s time to time (see Section ??). pys60_version A string containing the version number of the Python for S60 and some additional information. Example: 5 >>> import e32 >>> e32.pys60_version ’1.9.3 svn2793’ >>> pys60_version_info A tuple containing the five components of the Python for S60 version number: major, minor, micro, release tag, and serial. All values except release level are integers; the release tag is a string. A value other than ’final’ for the release tag signifies a development release. The pys60_version_info value corresponding to the Python for S60 version 1.9.3 is (1, 9, 3, ’svn2793’, 0). Example: >>> import e32 >>> e32.pys60_version_info (1, 9, 3, ’svn2793’, 0) >>> s60_version_info Returns the S60 platform version of the device. Example: >>> import e32 >>> e32.s60_version_info (3, 0) >>> is_ui_thread() Returns True if the code that calls this function runs in the context of the UI thread; otherwise returns False. start_exe(filename, command [,wait ]) Launches the native Symbian OS executable filename (Unicode) and passes it the command string. When wait is set, the function synchronously waits for the exit of the executable and returns a value that describes the exit type. Possible values are 0 for