nokia 12 gsm module - hmangas.com 12/nokia_12... · gprs general packet radio ... this document is...

C

opyr

ight

© 2

004

Nok

ia. A

ll rig

hts

rese

rved

. I

ssue

1.0

923

1720

NOKIA 12 GSM MODULE

INTERFACE DEFINITION REFERENCE GUIDE

Contents

ACRONYMS AND TERMS ......................................................................................................1 1 ABOUT THIS DOCUMENT ..............................................................................................2 2 INTRODUCTION..............................................................................................................3

2.1 PRODUCT CONCEPT...............................................................................................3 2.2 NOKIA 12 GSM MODULE INTERFACE DEFINITIONS ............................................3

2.2.1 Wireless Device Interface Definition.......................................................................3 2.2.2 Embedded Terminal Interface Definition ................................................................4 2.2.3 IO Interface Definition.............................................................................................4 2.2.4 IMlet Suite Manager Interface Definition ................................................................4 2.2.5 GPS Interface Definition.........................................................................................4

3 WIRELESS DEVICE INTERFACE DEFINITION..............................................................5 3.1 DEVICE INTERFACE ................................................................................................5

3.1.1 Data structures .......................................................................................................5

3.1.1.1 Version ........................................................................................................5 3.1.1.2 Counter........................................................................................................5

3.1.2 Exceptions..............................................................................................................6

3.1.2.1 UnknownObjectNameException..................................................................6 3.1.2.2 UnknownObjectNameListException ............................................................6 3.1.2.3 ParamFailureException ...............................................................................7 3.1.2.4 ParamFailureListException..........................................................................8 3.1.2.5 UnknownParamNameException..................................................................8 3.1.2.6 ParamAlreadyObservedException ..............................................................9 3.1.2.7 ParamObserverNotExistsException ............................................................9 3.1.2.8 UnknownCounterNameException ...............................................................9 3.1.2.9 UnknownCounterNameListException........................................................10 3.1.2.10 EventObserverNotExistsException............................................................10 3.1.2.11 EventNotExistsException ..........................................................................10

3.1.3 Method calls .........................................................................................................10

3.1.3.1 getObjectRef..............................................................................................10 3.1.3.2 getObjectRefList ........................................................................................11

3.1.3.3 getObjectNames........................................................................................11 3.1.3.4 getDeviceInfo.............................................................................................12 3.1.3.5 setParam ...................................................................................................12 3.1.3.6 getParam...................................................................................................13 3.1.3.7 setParamList..............................................................................................13 3.1.3.8 getParamList .............................................................................................14 3.1.3.9 setParamObserver ....................................................................................15 3.1.3.10 removeParamObserver .............................................................................15 3.1.3.11 getCounter.................................................................................................16 3.1.3.12 getCounterList ...........................................................................................16 3.1.3.13 setEventObserver......................................................................................17 3.1.3.14 removeEventObserver...............................................................................17 3.1.3.15 removeAllObservers ..................................................................................18 3.1.3.16 reset...........................................................................................................18

3.2 EVENTOBSERVER INTERFACE............................................................................18 3.2.1 Method calls .........................................................................................................18

3.2.1.1 eventFired..................................................................................................18 3.3 PARAMOBSERVER INTERFACE...........................................................................19

3.3.1 Method calls .........................................................................................................19

3.3.1.1 paramChanged..........................................................................................19 4 EMBEDDED TERMINAL INTERFACE DEFINITION .....................................................20

4.1 ET INTERFACE .......................................................................................................20 4.1.1 Data structures .....................................................................................................20

4.1.1.1 BearerInformationSMS ..............................................................................20 4.1.1.2 BearerInformationDataCall ........................................................................20 4.1.1.3 BearerInformationGPRS............................................................................21 4.1.1.4 BearerInformationUSSD............................................................................22 4.1.1.5 BearerInformationUnion ............................................................................22 4.1.1.6 BearerInformation......................................................................................23

4.1.2 Exceptions............................................................................................................24

4.1.2.1 GeneralFailureException ...........................................................................24 4.1.2.2 ShortMessageIndexOutOfRangeException...............................................26 4.1.2.3 ServiceCentreAddressUndefinedException ..............................................26 4.1.2.4 ShortMessageLocationEmptyException....................................................26

4.1.2.5 SecurityCodeRejectedException ...............................................................26 4.1.2.6 SecurityCodeNotRequiredException .........................................................27 4.1.2.7 SecurityCodeChangeDeniedException .....................................................27 4.1.2.8 CallIDNotInUseException ..........................................................................27 4.1.2.9 ConnectionParameterException................................................................28 4.1.2.10 ConnectionIDNotInUseException ..............................................................28 4.1.2.11 InvalidPasswordException.........................................................................28 4.1.2.12 PhonebookFailureException......................................................................29

4.1.3 Read only attributes .............................................................................................30

4.1.3.1 International Mobile Equipment Identity ....................................................30 4.1.4 Method calls .........................................................................................................30

4.1.4.1 sendShortMessage....................................................................................30 4.1.4.2 readShortMessage ....................................................................................30 4.1.4.3 removeShortMessage ...............................................................................31 4.1.4.4 changeSecurityCode .................................................................................32 4.1.4.5 setSecurityCode ........................................................................................32 4.1.4.6 initiateCall ..................................................................................................33 4.1.4.7 answerCall.................................................................................................33 4.1.4.8 dropCall .....................................................................................................34 4.1.4.9 dropAllCalls ...............................................................................................34 4.1.4.10 holdCall......................................................................................................34 4.1.4.11 retrieveCall ................................................................................................35 4.1.4.12 joinCall.......................................................................................................35 4.1.4.13 splitCall ......................................................................................................36 4.1.4.14 transferCall ................................................................................................36 4.1.4.15 swapCalls ..................................................................................................36 4.1.4.16 createConnection ......................................................................................37 4.1.4.17 setConnection............................................................................................37 4.1.4.18 closeConnection ........................................................................................38 4.1.4.19 destroyConnection.....................................................................................38 4.1.4.20 sendSSCode .............................................................................................39 4.1.4.21 setCallForwarding......................................................................................39 4.1.4.22 removeCallForwarding ..............................................................................40 4.1.4.23 getCallForwarding .....................................................................................41

4.1.4.24 setFacilityLock ...........................................................................................42 4.1.4.25 getFacilityLock...........................................................................................44 4.1.4.26 readPhonebookEntry.................................................................................45 4.1.4.27 findPhonebookEntry ..................................................................................46 4.1.4.28 editPhonebookEntry ..................................................................................47 4.1.4.29 addPhonebookEntry ..................................................................................47 4.1.4.30 removePhonebookEntry ............................................................................48 4.1.4.31 getPhonebookSize ....................................................................................49 4.1.4.32 generateDTMFTones ................................................................................50

5 IO INTERFACE DEFINITION.........................................................................................51 5.1 IO INTERFACE........................................................................................................51

5.1.1 Data structures .....................................................................................................51

5.1.1.1 AnalogAlarmLimits.....................................................................................51 5.1.2 Exceptions............................................................................................................51

5.1.2.1 PinNumberOutOfRange ............................................................................51 5.1.2.2 PinNumberOutOfRangeList.......................................................................52 5.1.2.3 PinValueOutOfRange ................................................................................53 5.1.2.4 PinValueOutOfRangeList ..........................................................................53 5.1.2.5 InvalidPinMode ..........................................................................................53 5.1.2.6 ObserverNotExists.....................................................................................54 5.1.2.7 LowLimitOutOfRange ................................................................................54 5.1.2.8 HighLimitOutOfRange ...............................................................................54 5.1.2.9 PeriodOutOfRange ....................................................................................54 5.1.2.10 ListsNotEven .............................................................................................55

5.1.3 Read only attributes .............................................................................................55

5.1.3.1 NumberOfInputPins ...................................................................................55 5.1.3.2 NumberOfOutputPins ................................................................................55

5.2 I/O CONTROL INTERFACE ....................................................................................55 5.2.1 Method calls .........................................................................................................55

5.2.1.1 setIOControlObserver................................................................................55 5.2.1.2 removeIOControlObserver ........................................................................56 5.2.1.3 getInputPinMode .......................................................................................57 5.2.1.4 getInputPinAlarmLimits..............................................................................57 5.2.1.5 getInputPinAlarmPeriod.............................................................................58

5.2.1.6 setInputPinModeAlarming .........................................................................58 5.2.1.7 setInputPinModePeriodical........................................................................59 5.2.1.8 getInputPinValue .......................................................................................60 5.2.1.9 getInputPinValueList..................................................................................60 5.2.1.10 setOutputPinValue.....................................................................................61 5.2.1.11 setOutputPinValueList ...............................................................................61 5.2.1.12 getOutputPinValue ....................................................................................62 5.2.1.13 getOutputPinValueList...............................................................................62

5.3 IOCONTROLOBSERVER INTERFACE ..................................................................63 5.3.1 Method calls .........................................................................................................63

5.3.1.1 pinStateChanged.......................................................................................63 6 IMLET SUITE MANAGER INTERFACE DEFINITION ...................................................65

6.1 DATA STRUCTURES..............................................................................................65 6.1.1 SuiteInformation ...................................................................................................65

6.2 EXCEPTIONS..........................................................................................................66 6.2.1 LoadException......................................................................................................66 6.2.2 SuiteManagerException .......................................................................................66

6.3 RUNTIMELISTENER INTERFACE..........................................................................68 6.3.1 Method calls .........................................................................................................68

6.3.1.1 runtimeEvent .............................................................................................68 6.4 IMLET INTERFACE .................................................................................................69

6.4.1 Method calls .........................................................................................................69

6.4.1.1 start............................................................................................................69 6.4.1.2 stop............................................................................................................70 6.4.1.3 getStatus ...................................................................................................70 6.4.1.4 getName ....................................................................................................71 6.4.1.5 getSuiteName............................................................................................71

6.5 SUITE INTERFACE .................................................................................................72 6.5.1 Method calls .........................................................................................................72

6.5.1.1 getIMlet......................................................................................................72 6.5.1.2 getIMletNameList.......................................................................................73 6.5.1.3 getInformation............................................................................................73

6.6 SUITELOADER INTERFACE ..................................................................................73 6.6.1 Method calls .........................................................................................................73

6.6.1.1 loadSuitePacket.........................................................................................73 6.6.1.2 terminalSuiteLoad......................................................................................74

6.7 SUITEMANAGER INTERFACE...............................................................................74 6.7.1 Method calls .........................................................................................................75

6.7.1.1 prepareSuiteLoad ......................................................................................75 6.7.1.2 removeSuite ..............................................................................................76 6.7.1.3 getSuite .....................................................................................................76 6.7.1.4 getSuiteNameList ......................................................................................77 6.7.1.5 getFreeMemory .........................................................................................77 6.7.1.6 getMaxPacketSize.....................................................................................77 6.7.1.7 removeAllSuites.........................................................................................78 6.7.1.8 getActiveIMlets ..........................................................................................78 6.7.1.9 setRuntimeListener....................................................................................78 6.7.1.10 removeRuntimeListener ............................................................................79

7 GPS INTERFACE DEFINITION .....................................................................................81 7.1 GPSMODULE INTERFACE.....................................................................................81

7.1.1 Data structures .....................................................................................................81

7.1.1.1 Coordinate .................................................................................................81 7.1.1.2 Location .....................................................................................................82 7.1.1.3 Vector ........................................................................................................82 7.1.1.4 GpsData ....................................................................................................82

7.1.2 Exceptions............................................................................................................83

7.1.2.1 NoGpsDataAvailableException .................................................................83 7.1.3 Method calls .........................................................................................................83

7.1.3.1 getGpsData ...............................................................................................83

Legal Notice

Copyright © 2004 Nokia. All rights reserved.

Reproduction, transfer, distribution or storage of part or all of the contents in this document in any form without the prior written permission of Nokia is prohibited.

Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation. 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.

Nokia operates a policy of continuous development. Nokia reserves the right to make changes and improvements to any of the products described in this document without prior notice.

Under no circumstances shall Nokia be responsible for any loss of data or income or any special, incidental, consequential or indirect damages howsoever caused.

The contents of this document are provided "as is". Except as required by applicable law, no warranties of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose, are made in relation to the accuracy, reliability or contents of this document. Nokia reserves the right to revise this document or withdraw it at any time without prior notice.

ACRONYMS AND TERMS

Acronym/term Description

AM Application Module

AT ATtention (command language)

CHAP Challenge Handshake Authentication Protocol

CLDC Connected Limited Device Configuration

CORBA Common Object Request Broker Architecture

DTMF Dual Tone Multi-frequency

GPRS General Packet Radio Service

GSM Global System for Mobile Communications

GPS Global Positioning System

IDL Interface Definition Language

IMEI International Mobile Equipment Identity

I/O Input/Output

IP Internet Protocol

JAR Java™ Archive

J2ME™ Java 2 Micro Edition

M2M Machine-to-Machine

MO Mobile-originated

MT Mobile-terminated

MSISDN Mobile Station ISDN Number

OTA Over-the-Air

PIN Personal Identity Number

PUK Personal Unblocking Key

SIM Subscriber Identity Module

SMS Short Message Service

TCP Transmission Control Protocol

UDP User Datagram Protocol

USSD Unstructured supplementary services data

WTP Wireless Transaction Protocol

1/84

1 ABOUT THIS DOCUMENT

This document is an interface definition reference guide for the Nokia 12 GSM module (hereafter Nokia 12 module).

This document gives detailed information about the Nokia 12 module services that are available for the application developer when the Nokia 12 module is used for Machine-to-Machine (M2M) communication.

2/84

2 INTRODUCTION

2.1 PRODUCT CONCEPT The Nokia 12 module is an M2M communication device that provides wireless connectivity and remote management possibilities for different applications.

The Nokia 12 module has two variants: RX-2 and RX-9. The RX-2 variant supports EGSM 900/GSM1800 networks and CSD/HSCSD, GPRS/EGPRS, and SMS bearers. The RX-9 variant supports GSM850/1900 networks and CSD, GPRS/EGPRS, and SMS bearers.

The Nokia 12 module can be used:

• to download, test and execute JavaTM IMlets

• with Transmission Control Protocol (TCP)/ User Datagram Protocol (UDP) via the M2M System Protocol 2 socket interface

• with AT commands as a wireless GSM modem

• with input and output pins that can be controlled with text message templates

For more information on the features of the Nokia 12 module, please refer to the Nokia 12 GSM Module Product Specification, Nokia M2M System Protocol 2 Specification and to other M2M documents at http://www.forum.nokia.com or http://www.americas.forum.nokia.com.

2.2 NOKIA 12 GSM MODULE INTERFACE DEFINITIONS The services offered by the Nokia 12 module are defined in the following interface definitions:

• Wireless Device Interface Definition

• Embedded Terminal Interface Definition

• IO Interface Definition

• IMlet Suite Manager Interface Definition

• GPS Interface Definition

2.2.1 Wireless Device Interface Definition The Wireless Device Interface Definition is common for all kinds of devices. The services defined in the Wireless Device Interface Definition are divided into three interfaces:

3/84

http://www.forum.nokia.com/

http://www.americas.forum.nokia.com/

• Device

• ParamObserver

• EventObserver

The Device interface has functions to handle dynamic parameters and counters. The services of the EventObserver interface are used to provide information on unusual events like incoming calls or a network connection loss. The functions of the ParamObserver interface are used in the same way, but only to receive notification of changes in dynamic parameters. The parameters and events of these interfaces are defined in a separate Properties Interface Definition that is described in the Nokia 12 GSM Module Properties Reference Guide.

2.2.2 Embedded Terminal Interface Definition Services specific to Nokia 12 modules are described in the Embedded Terminal Interface Definition. It describes GSM-related operations, such as call control, SMS, and supplementary services. They provide an easy access to basically all mobile network services.

2.2.3 IO Interface Definition Services related to remote input/output (I/O) control are described in the IO Interface Definition. It has functions for remote control of the input and output pins in the M2M System Connector. The IOControlObserver interface is used for indicating changes in these pins.

2.2.4 IMlet Suite Manager Interface Definition The IMlet Suite Manager Interface Definition has functions to control the life cycle of IMlet Suites inside the Nokia 12 module. This service can be used, for example, to load IMlets to, start and stop them in, and remove them from the Nokia 12 module.

2.2.5 GPS Interface Definition The GPS Interface Definition has functions to read parameters specific to the Global Positioning System (GPS) from a GPS device that is physically attached to the Nokia 12 module.

4/84

3 WIRELESS DEVICE INTERFACE DEFINITION

The object that implements this interface definition in the Nokia 12 module can be located by using the following object key:

Device

3.1 DEVICE INTERFACE

3.1.1 Data structures

3.1.1.1 Version struct Version { octet major; octet minor; short build; long date; };

Description: Version data structure contains version information. It is used for indicating software and hardware versions of the Nokia 12 module.

Members: Data member Description

major Major version number.

minor Minor version number.

build Build number.

date Date information. Given as seconds since 1st January 1970.

See also: getDeviceInfo

3.1.1.2 Counter struct Counter { string name; boolean reset; };

5/84

Description: Counter data structure contains counter information. It is used when counter values are queried. Refer to the Nokia 12 GSM Module Properties Reference Guide for more information on counters.


name Name of the counter.

reset Reset flag.

Possible values:

TRUE Counter is reset when read

FALSE Counter is not reset when read

See also: getCounter

getCounterList

3.1.2 Exceptions

3.1.2.1 UnknownObjectNameException exception UnknownObjectNameException { };

Description: Exception is used for indicating invalid object name in getObjectRef method call.

See also: getObjectRef

3.1.2.2 UnknownObjectNameListException exception UnknownObjectNameListException { long index };

Description: Exception is used for indicating the first invalid object name in the getObjectRefList method call.

Members: Member Description

6/84

Member Description

index Number of the first failed parameter.

See also: getObjectRefList

3.1.2.3 ParamFailureException exception ParamFailureException { ParamFailureReason reason };

Description: Exception is used for indicating failures in parameter handling. It can be sent as a response either to the setParam or getParam method call.


reason Reason for failure.

Possible values:

INVALID_NAME

Parameter name was invalid

INVALID_TYPECODE

Common Object Request Broker Architecture (CORBA) typecode for the given parameter was invalid

READ_ONLY

Parameter is read only

NOT_AVAILABLE

Parameter is not currently available

INVALID_VALUE

Given value was invalid

CODE_REJECTED

Given code was rejected due to a wrong PIN2 code

CODE_BLOCKED

Given PIN2 code was blocked and has to be unblocked

See also: setParam

getParam

7/84

3.1.2.4 ParamFailureListException exception ParamFailureListException { long index; ParamFailureReason reason; };

Description: Exception is used for indicating failures in parameter list handling. It can be sent as a response either to the setParamList or getParamList method call.


Index Number of the first failed parameter. Numbering of the index starts from one (1).

Reason Reason for failure.

Possible values:

INVALID_NAME

Parameter name was invalid

INVALID_TYPECODE

CORBA typecode for the given parameter was invalid

READ_ONLY

Parameter is read only

NOT_AVAILABLE

Parameter is not currently available

INVALID_VALUE

Given value was invalid

CODE_REJECTED

Given code was rejected due to a wrong PIN2 code.

CODE_BLOCKED

Given PIN2 code was blocked and has to be unblocked.

See also: setParamList

getParamList

3.1.2.5 UnknownParamNameException exception UnknownParamNameException { };

8/84

Description: Exception is used for indicating that the parameter requested for observation was not found. It can be sent as a response to the setParamObserver method call.

See also: setParamObserver

3.1.2.6 ParamAlreadyObservedException exception ParamAlreadyObservedException { };

Description: Exception is used for indicating that the observer for the parameter requested for observation is already registered. It can be sent as a response to the setParamObserver method call.

See also: setParamObserver

3.1.2.7 ParamObserverNotExistsException exception ParamObserverNotExistsException { };

Description: Exception is used for indicating that the observer that was to be removed had not been registered. It can be sent as a response to the removeEventObserver method call.

See also: removeEventObserver

3.1.2.8 UnknownCounterNameException exception UnknownCounterNameException { };

Description: Exception is used for indicating that the given counter name was not found. It can be sent as a response to the getCounter method call.

See also: getCounter

9/84

3.1.2.9 UnknownCounterNameListException exception UnknownCounterNameListException { long index };

Description: Exception is used for indicating that at least one of the given counter names was not found. It can be sent as a response to the getCounterList method call.


index First counter name that was not found.

See also: getCounterList

3.1.2.10 EventObserverNotExistsException exception EventObserverNotExistsException { };

Description: Exception is used for indicating that the given observer was not found. It can be sent as a response to the removeEventObserver method call.

See also: removeEventObserver

3.1.2.11 EventNotExistsException exception EventNotExistsException { };

Description: Exception is used for indicating that the given event was not found. It can be sent as a response to the setEventObserver method call.

See also: setEventObserver

3.1.3 Method calls

3.1.3.1 getObjectRef Object getObjectRef( in string name );

10/84

Description: Method call returns an object reference to the wanted object. The name that is used as an input parameter can be fetched, for example, with the getObjectNames method call. With the Nokia 12 module, this method can be called regardless of the caller’s location.


name Name of the wanted object.

Return values: Value Description

Object reference Method call returned successfully.

See also: UnknownObjectNameException

3.1.3.2 getObjectRefList ObjectList getObjectRefList( in ObjectNameList names );

Description: Method call returns a list of object references to wanted objects. With Nokia 12 modules, this method can be called regardless of the caller’s location.


names List of the wanted object names. Given as a sequence of strings.


List of object references Method call returned successfully.

See also: UnknownObjectNameListException

3.1.3.3 getObjectNames ObjectNameList getObjectNames( );

11/84

Description: Method call returns a list of object names. This method call is usually used together with the getObjectRef or getObjectRefList method.


List of object names Method call returned successfully. Return value given as a sequence of strings.

3.1.3.4 getDeviceInfo void getDeviceInfo( out string hwManufacturer, out string hwProductName, out Version hwVersion, out string swManufacturer, out string swProductName, out Version swVersion, out MetadataList metadata );

Description: Method call returns information about the device.


hwManufacturer Name of the hardware manufacturer.

hwProductName Name of the hardware product.

HwVersion Hardware version information.

swManufacturer Name of the software manufacturer.

swProductName Type designation of the Nokia 12 module.

swVersion Software version information.

metadata Vendor-specific information. Given as a sequence of strings.

See also: Version

3.1.3.5 setParam void setParam( in ParamName name, in any value );

12/84

Description: Method call is used for modifying the parameter values of the Nokia 12 module. Some parameters require special conditions like the service state and an inserted Subscriber Identity Module (SIM) card before they can be set. Refer to the Nokia 12 GSM Module Properties Reference Guide for parameters that can be set using this function.


name Name of the parameter to be set.

value New value for the parameter to be set. The input parameter must be of the CORBA type any. An any type value can be created using a code generated from the Properties Interface Definition.

See also: ParamFailureException

3.1.3.6 getParam void getParam( in ParamName name, out any value );

Description: Method call is used for retrieving parameter values. Some parameters require special conditions like the service state and an inserted SIM card before they can be requested. Refer to the Nokia 12 GSM Module Properties Reference Guide for parameters that can be retrieved using this function.


name Name of the parameter to be retrieved.

value Retrieved parameter value. The parameter is of the CORBA type any. An any type value can be extracted using a code generated from the Properties Interface Definition.

See also: ParamFailureException

3.1.3.7 setParamList void setParamList( in ParamNameList pnl, in ParamValueList pvl );

13/84

Description: Method call is used for modifying multiple parameter values. Some parameters require special conditions like the service state and an inserted SIM card before they can be set. Refer to the Nokia 12 GSM Module Properties Reference Guide for parameters that can be set using this function.


pnl List of parameter names to be modified. Given as a sequence of strings.

pvl New values for parameters. Given as a sequence of the CORBA type any. An any type value can be created using a code generated from the Properties Interface Definition.


ParamFailureListException Setting new values for parameters was not successful. The first parameter that was not successful is returned in the exception.

See also: ParamFailureListException

3.1.3.8 getParamList void getParamList( in ParamNameList pnl, out ParamValueList pvl );

Description: Method call is used for retrieving multiple parameter values. Some parameters require special conditions like the service state and an inserted SIM card before they can be requested. Refer to the Nokia 12 GSM Module Properties Reference Guide for parameters that can be retrieved using this function.


pnl List of parameter names to be retrieved. Given as a sequence of strings.

pvl List of retrieved parameter values. Given as a sequence of parameters of the CORBA type any. An any type value can be created using a code generated from the Properties Interface Definition.

14/84

See also: ParamFailureListException

3.1.3.9 setParamObserver void setParamObserver( in ParamName name, in ParamObserver po );

Description: Method call is used for registering a parameter observer. Additional parameters can be registered to the same observer object with a different name. One parameter can have more than one observer registered at a time. Refer to the Nokia 12 GSM Module Properties Reference Guide for possible parameters, and to the Nokia 12 GSM Module Java IMlet Programming Guide for instructions on how to use the observers.


name Name of the observed parameter.

po Reference to the parameter observer.

See also: ParamObserver interface

UnknownParamNameException

ParamAlreadyObservedException

3.1.3.10 removeParamObserver void removeParamObserver( in ParamName name, in ParamObserver po );

Description: Method call is used for cancelling a parameter observer. The observer is not removed until the removeParamObserver method is called for all parameters that the observer has been set to observe. Refer to the Nokia 12 GSM Module Properties Reference Guide for possible parameters.


name Name of the removed parameter.

po Reference to the parameter observer.

15/84

See also: ParamObserver interface

UnknownParamNameException

ParamObserverNotExistsException

3.1.3.11 getCounter void getCounter( in Counter c, out CounterValue value );

Description: Method call is used for retrieving counter values. Some counters can also be reset with a reset flag. Refer to the Nokia 12 GSM Module Properties Reference Guide for more information on counters.


c Counter to be retrieved. Contains the counter name and reset flag.

value Retrieved counter value.

See also: Counter

UnknownCounterNameException

3.1.3.12 getCounterList void getCounterList( in CounterList c, out CounterValueList values );

Description: Method call is used for retrieving a list of counter values. Some counters can also be reset with a reset flag. Refer to the Nokia 12 GSM Module Properties Reference Guide for more information on counters.


c List of counters to be retrieved. Given as a sequence of counter structures. Contains counter names and reset flags.

values List of retrieved counter values. Given as a sequence of longs.

16/84

See also: Counter

UnknownCounterNameListException

3.1.3.13 setEventObserver void setEventObserver( in string name, in EventObserver o );

Description: Method call is used for registering an event observer. Additional events can be registered to the same observer object with a different name. One event can have more than one observer registered at a time. Refer to the Nokia 12 GSM Module Properties Reference Guide for possible events and to the Nokia 12 GSM Module Java IMlet Programming Guide for instructions on how to use the observers.


name Name of the observer event.

o Reference to the observer object.

See also: EventObserver interface

EventNotExistsException

removeAllObservers

3.1.3.14 removeEventObserver void removeEventObserver( in string name, in EventObserver o );

Description: Method call is used for cancelling an event observer. The observer is not removed until the removeEventObserver method is called for all events that the observer has been set to observe. Refer to the Nokia 12 GSM Module Properties Reference Guide for possible events.


name Name of the removed event.

o Reference to the observer object.

17/84

See also: EventObserver interface

EventObserverNotExistsException

removeAllObservers

3.1.3.15 removeAllObservers

void removeAllObservers();

Description: Method call is used for removing all kinds of observers (event, parameter, I/O, and IMlet) of the Nokia 12 module regardless of who has set them. After this method call, the Nokia 12 module does not send any observer events until a new observer is set.

3.1.3.16 reset void reset();

Description: Method call is used for resetting the device. There may be a short delay between the method call and the actual reset procedures. The reset equals to a switch-off: calls are disconnected but all the settings remain unchanged.

3.2 EVENTOBSERVER INTERFACE

3.2.1 Method calls

3.2.1.1 eventFired void eventFired( in string name, in any eventData );

Description: The Nokia 12 module calls the eventFired method of the event observer implementation in the customer application that has been registered to listen for that particular event with the setEventObserver method. The eventFired method call is used for indicating that an event has occurred. Refer to the Nokia 12 GSM Module Properties Reference Guide for possible events and to the Nokia 12 GSM Module Java IMlet Programming Guide for instructions on how to use the observers.

18/84


name Name of the event.

eventData Data associated with the current event and situation.


removeEventObserver

removeAllObservers

3.3 PARAMOBSERVER INTERFACE

3.3.1 Method calls

3.3.1.1 paramChanged void paramChanged( in string name, in any oldValue, in any newValue );

Description: The Nokia 12 module calls the paramChanged method of the parameter observer implementation in the customer application that has been registered to listen for the changes of that particular parameter with the setParamObserver method. The paramChanged method call is used for indicating that the parameter state has changed. Refer to the Nokia 12 GSM Module Properties Reference Guide for possible parameters and to the Nokia 12 GSM Module Java IMlet Programming Guide for instructions on how to use the observers.


name Name of the parameter.

oldValue Value of the parameter before the change.

newValue Value of the parameter after the change.


removeEventObserver

removeAllObservers

19/84

4 EMBEDDED TERMINAL INTERFACE DEFINITION

The object that implements this interface definition in the Nokia 12 module can be located using the following object key:

ORB/OA/IDL:ET:1.0

4.1 ET INTERFACE


4.1.1.1 BearerInformationSMS struct BearerInformationSMS { string GW_number; unsigned short GW_port; };

Description: BearerInformationSMS data structure contains information about SMS bearer use. It is used when making connections to a server.


GW_number Server number when SMS is used as the wireless bearer.

GW_port Port number of the server Connection Provider (CP) that is used with this bearer.

See also: BearerInformationUnion

createConnection

4.1.1.2 BearerInformationDataCall struct BearerInformationDataCall { string GW_number; string GW_ipaddr; unsigned short GW_port; string CHAP_username; string CHAP_password; };

20/84

Description: BearerInformationDataCall data structure contains information about data call bearer use. It is used when making connections to a server.


GW_number Server number when data call is used as the wireless bearer.

GW_ipaddr Server IP address. Given in the format of a dotted IPv4 address, for example, 10.10.10.10.

GW_port Port number of the server that is used with this bearer.

CHAP_username Challenge Handshake Authentication Protocol (CHAP) username.

CHAP_password CHAP password associated with the used username.

See also: BearerInformationDataCall

createConnection

4.1.1.3 BearerInformationGPRS struct BearerInformationGPRS { string GW_apn; string GW_ipaddr; unsigned short GW_port; string CHAP_username; string CHAP_password; };

Description: BearerInformationGPRS data structure contains information about GPRS bearer use. It is used when making connections to a server.


GW_apn Access point name when GPRS is used as the wireless bearer.

GW_ipaddr Server IP address. Given in the format of a dotted IPv4 address, for example, 10.10.10.10.

GW_port Port number of the server that is used with this bearer.

CHAP_username CHAP username.

21/84

Member Description

CHAP_password CHAP password associated with the used username.


createConnection

4.1.1.4 BearerInformationUSSD struct BearerUSSDConnectionAddress { case IP_ADDRESS: string GWIPAddress; case MSISDN_ADDRESS: string destinationNumber; }; struct BearerInformationUSSD { string GWNumber; BearerUSSDConnectionAddress connectionAddress; };

Note: The Nokia 12 module does not support USSD as an application level data bearer.

4.1.1.5 BearerInformationUnion union BearerInformationUnion switch( BearerType ) { case SMS: BearerInformationSMS smsInfo; case DATA_CALL: BearerInformationDataCall dataCallInfo; case GPRS: BearerInformationGPRS gprsInfo; case USSD: BearerInformationUSSD USSDInfo; };

Description: BearerInformationUnion data structure contains information about different bearers. It is used when making connections to a server.


smsInfo Server information when SMS is used as the wireless bearer.

dataCallInfo Server information when data call is used as the wireless bearer.

gprsInfo Server information when GPRS is used as the wireless b

22/84

Member Description bearer.

USSDInfo Server information when USSD is used as the wireless bearer.

BearerType Type of the bearer. Possible values of the BearerType enumeration type:

SMS SMS as the bearer

DATA_CALL Data call as the bearer

GPRS GPRS as the bearer

USSD USSD as the bearer

See also: BearerInformationSMS

BearerInformationDataCall

BearerInformationGPRS

BearerInformation

createConnection

4.1.1.6 BearerInformation struct BearerInformation { BearerInformationUnion gateway; unsigned short WTP_port; };

Description: BearerInformation data structure contains information about the wireless bearer to be used and the Wireless Transaction Protocol (WTP) port of the Nokia 12 module. It is used when making connections to a server.

BearerInformation data structure is used to define dynamic connections that are stored in volatile memory. Connections stored in non-volatile memory are defined via the Properties Interface Definition. Refer to the Nokia 12 GSM Module Properties Reference Guide for more information on these connections.


23/84

Member Description

gateway Server information; bearer to be used.

WTP_port Nokia 12 module application port number.


createConnection

4.1.2 Exceptions

4.1.2.1 GeneralFailureException exception GeneralFailureException { FailureReason reason };

Description: Exception is used for indicating general GSM-specific failures. It can be raised by the following method calls: sendShortMessage, removeShortMessage, initiateCall, dropCall, dropAllCalls, holdCall, retrieveCall, joinCall, splitCall, transferCall, swapCalls, setCallForwarding, removeCallForwarding, getCallForwarding, or generateDTMFTones.



Possible values of the FailureReason enumeration type:

SIM_CARD_MISSING

SIM card is missing

NOT_IN_SERVICE

Nokia 12 module is not in service

SECURITY_CODE_REQUIRED

A security code (for example a PIN code) is required. Getting the parameter LockStatus can retrieve more specific information about the queried security code.

INVALID_DESTINATION

Call or SMS destination was invalid

NUMBER_TOO_LONG

The given phone number was too long

RESOURCE_RESERVED

The required resource for operation was reserved

24/84

Member Description

SIM_NOT_READY

SIM card is not ready yet

INVALID_STATE

Nokia 12 module is not in a valid state for the current operation.

LIMIT_REACHED

The current operation cannot be completed due to an exceeded limit. The limitations are operation-specific.

NETWORK_ERROR

The current operation cannot be completed due to an error in the network.

BLACKLIST_ERROR

The current operation cannot be completed because the number is blacklisted.

See also: sendShortMessage

readShortMessage

removeShortMessage

initiateCall

answerCall

dropCall

dropAllCalls

holdCall

retrieveCall

joinCall

splitCall

transferCall

swapCalls

setCallForwarding

removeCallForwarding

25/84

getCallForwarding

generateDTMFTones

4.1.2.2 ShortMessageIndexOutOfRangeException exception ShortMessageIndexOutOfRangeException { };

Description: Exception is used for indicating that the index used in a short message method calls was invalid. It can be raised by the readShortMessage and removeShortMessage method calls.

See also: readShortMessage

removeShortMessage

4.1.2.3 ServiceCentreAddressUndefinedException exception ServiceCentreAddressUndefinedException { };

Description: Exception is used for indicating that the address of the Short Message Service Centre (SMSC) is not defined and short messages cannot be sent. It can be raised by the sendShortMessage method call.

See also: sendShortMessage

4.1.2.4 ShortMessageLocationEmptyException exception ShortMessageLocationEmptyException { };

Description: Exception is used for indicating that the processed location was empty. It can be raised by the readShortMessage and removeShortMessage method calls.

See also: readShortMessage

removeShortMessage

4.1.2.5 SecurityCodeRejectedException exception SecurityCodeRejectedException { };

26/84

Description: Exception is used for indicating that the Nokia 12 module did not accept the given security code. It can be raised by the changeSecurityCode method call.

See also: changeSecurityCode

4.1.2.6 SecurityCodeNotRequiredException exception SecurityCodeNotRequiredException { };

Description: Exception is used for indicating that the Nokia 12 module did not require the given security code. It can be raised by the setSecurityCode method call.

See also: setSecurityCode

4.1.2.7 SecurityCodeChangeDeniedException exception SecurityCodeChangeDeniedException { };

Description: Exception is used for indicating that the security code change was not successful. One reason for this could be that the pin code requirement has not been set. The exception can be raised by the changeSecurityCode method call.

See also: changeSecurityCode

4.1.2.8 CallIDNotInUseException exception CallIDNotInUseException { };

Description: Exception is used for indicating that the given ID is not in use. It can be raised by the following method calls: answerCall, dropCall, holdCall, retrieveCall, splitCall, joinCall, transferCall, or swapCalls.

See also: answerCall

dropCall

27/84

holdCall

retrieveCall

joinCall

splitCall

transferCall

swapCalls

4.1.2.9 ConnectionParameterException exception ConnectionParameterException { };

Description: Exception is used for indicating that at least one of the given parameters was invalid. It can be raised by the createConnection method call.

See also: createConnection

4.1.2.10 ConnectionIDNotInUseException exception ConnectionIDNotInUseException { };

Description: Exception is used for indicating that the given ID is not in use. It can be raised by the following method calls: setConnection, closeConnection, or destroyConnection.

See also: setConnection

closeConnection

destroyConnection

4.1.2.11 InvalidPasswordException exception InvalidPasswordException { };

Description: Exception is used for indicating that the given password was invalid. It can be raised by the setFacilityLock method call.

28/84

See also: setFacilityLock

4.1.2.12 PhonebookFailureException exception PhonebookFailureException { PhonebookFailureReason reason };

Description: Exception is used for indicating phonebook-specific failures. It can be raised by the following method calls: readPhonebookEntry, findPhonebookEntry, editPhonebookEntry, addPhonebookEntry, or removePhoneEntry.



Possible values of the PhonebookFailureReason enumeration type are:

INDEX_OUT_OF_RANGE

Given index value was not within range

INVALID_NUMBER

Phone number is invalid

ENTRY_NOT_FOUND

The wanted entry was not found

EMPTY_ENTRY

The used entry is empty

READ_ONLY

Entry is read only

PHONEBOOK_FULL

The used phonebook is full

INVALID_NAME

Name is invalid

PHONEBOOK_UNAVAILABLE

The wanted phonebook is not currently available

See also: readPhonebookEntry

findPhonebookEntry

editPhonebookEntry

29/84

addPhonebookEntry

removePhonebookEntry

4.1.3 Read only attributes

4.1.3.1 International Mobile Equipment Identity

Description: Attribute returns the International Mobile Equipment Identity (IMEI) of the Nokia Nokia 12 module.

4.1.4 Method calls

4.1.4.1 sendShortMessage void sendShortMessage( in PhoneNumber phoneNumber, in string message, out long reference );

Description: Method call is used for sending short messages with the Nokia 12 module. Short messages can only be sent when the Nokia 12 module is in the service state.


phoneNumber Number of the message receiver.

message Message to be sent.

reference Reference number given by the Nokia 12 module. The number is used in short message related events.

See also: GeneralFailureException

ServiceCentreAddressUndefinedException

4.1.4.2 readShortMessage void readShortMessage( in MessageStorage ms, in long index, out string message, out PhoneNumber phoneNumber );

30/84

Description: Method call is used for reading short messages from the specified message storage.


ms The used message storage.

Possible values of the MessageStorage enumeration type:

PHONE Phone storage

SIM SIM storage

index Index of the message to be retrieved.

message Retrieved message.

phoneNumber Retrieved message sender.


ShortMessageIndexOutOfRangeException

ShortMessageLocationEmptyException

4.1.4.3 removeShortMessage void removeShortMessage( in MessageStorage ms, in long index );

Description: Method call is used for removing short messages from the specified message storage.


ms The used message storage.

Possible values of the MessageStorage enumeration type:

PHONE Phone storage

SIM SIM storage

index Index of the message to be removed.


31/84

ShortMessageIndexOutOfRangeException

ShortMessageLocationEmptyException

4.1.4.4 changeSecurityCode void changeSecurityCode( in SecurityCodeType sct, in string oldCode, in string newCode );

Description: Method call is used for changing security codes.


sct Type of the changed security code.

Possible values of the SecurityCodeType enumeration type:

PIN_CODE PIN code

PIN2_CODE PIN unblocking code

PUK_CODE PUK code

PUK2_CODE PUK unblocking code

SECURITY_CODE Security code

CALLBARRING_CODE Call barring code

oldCode Old code.

newCode New code.


SecurityCodeRejectedException

SecurityCodeChangeDeniedException

4.1.4.5 setSecurityCode void setSecurityCode( in SecurityCodeType sct, in string code );

Description: Method call is used for setting a security code queried by the Nokia 12 module. The Nokia 12 module queries security codes by sending a SECURITYCODE-REQUIRED event. When the code is accepted, a SECURITYCODE-ACCEPTED event is sent.

32/84

Note: If a wrong PIN code is entered three times in a row, the setSecurityCode method call raises a SecurityCodeNotRequired exception. A PUK code must be entered after the exception.


sct Type of the changed security code.

Possible values of the SecurityCodeType enumeration type:

PIN_CODE PIN code

PIN2_CODE PIN unblocking code

PUK_CODE PUK code

PUK2_CODE PUK unblocking code

SECURITY_CODE Security code

CALLBARRING_CODE Call barring code

code Code to be set.

See also: SecurityCodeNotRequiredException

4.1.4.6 initiateCall void initiateCall( in PhoneNumber phoneNumber, out CallID id );

Description: Method call is used for initiating mobile-originated (MO) voice calls. The Nokia 12 module needs to be in the service state for the method call to be successful. Calls initiated with the initiateCall method are always voice calls.


phoneNumber Number of the called party.

id Identifier for a successful call.


4.1.4.7 answerCall void answerCall( in CallID id );

33/84

Description: Method call is used for answering mobile-terminated (MT) voice calls


id Call identifier.


CallIDNotInUseException

4.1.4.8 dropCall void dropCall( in CallID id );

Description: Method call is used for dropping either MO or MT calls.


id Call identifier.



4.1.4.9 dropAllCalls void dropAllCalls( );

Description: Method call is used for dropping all calls that are active in the Nokia 12 module. Calls can be MO or MT calls and they can be in any state.

4.1.4.10 holdCall void holdCall( in CallID id );

Description: Method call is used for putting the chosen call on hold. The call has to be in an active state

34/84


id Call identifier.



4.1.4.11 retrieveCall void retrieveCall( in CallID id );

Description: Method call is used for retrieving a call on hold and activating it.


id Call identifier.



4.1.4.12 joinCall void joinCall( in CallID id );

Description: Method call is used for joining active calls and calls on hold together and thus making a conference call.


id Call identifier.



35/84

4.1.4.13 splitCall void splitCall( in CallID id );

Description: Method call is used for splitting one member from a conference call to a private call. After splitting, the private call becomes active and the conference call is put on hold.


id Call identifier.



4.1.4.14 transferCall void transferCall( in CallID id );

Description: Method call is used for transferring an active call to another party that is on hold.


id Call identifier.



4.1.4.15 swapCalls void swapCalls( in CallID id );

Description: Method call is used for swapping between an active call and a call on hold.


36/84

Member Description

id Call identifier.



4.1.4.16 createConnection ConnectionID createConnection( in BearerInformation connectionData );

Description: Method call is used for creating new connections. Connections are used for connecting the Nokia 12 module to a server using one of the supported bearers. A connection is created for each bearer that is to be used. The created connection is dynamic meaning that it is not stored in non-volatile memory. After creating the initial connections, the bearers can be changed by changing the connection with the setConnection method call.


connectionData Connection-specific bearer information.


Connection identifier The method call was successful. The identifier is used in other connection control functions.

See also: BearerInformation

ConnectionParameterException

4.1.4.17 setConnection ConnectionID setConnection( in ConnectionID connectionId );

Description: Method call is used for setting a connection created by the createConnection method to be used in the Nokia 12 module. The setConnection method is used for incoming connection sessions.

37/84


connectionId New connection ID.


Connection identifier The method call was successful. The identifier is the previously used connection identifier.

See also: ConnectionIDNotInUseException

4.1.4.18 closeConnection void closeConnection( in ConnectionID connectionId );

Description: Method call is used for closing a connection in use. Closing connections is not relevant if connections are used with the SMS bearer. When using the data call bearer, the closeConnection method drops an active data call. The same connection can still be used after the call is dropped.


connectionId ID of the connection to be closed.


4.1.4.19 destroyConnection void destroyConnection( in ConnectionID connectionId );

Description: Method call is used for deleting connections from the Nokia 12 module. Connections that are destroyed cannot be used for communication anymore and have to be recreated.


connectionId ID of the connection to be destroyed.

38/84


4.1.4.20 sendSSCode boolean sendSSCode( in string data );

Description: Method call is used for sending supplementary service codes.

Note: It is not advisable to use supplementary service codes when changing PIN and PIN2 codes. The changeSecurityCode method call must be used instead (see changeSecurityCode).


data Supplementary services code.


Active status Boolean value indicates whether the service is active or not.


4.1.4.21 setCallForwarding void setCallForwarding( in CallForwardReason cfr, in PhoneNumber phoneNumber, in ConnectionClassList ccl, in short time );

Description: Method call is used for setting call forwarding services. The Nokia 12 module needs to be in the service state when the call forwarding is set.


cfr Reason for call forwarding.

Possible values of the CallForwardType enumeration type:

39/84

Member Description

UNCONDITIONAL Forward all unconditional calls

BUSY Forward when busy

NO_REPLY Forward when no reply

NOT_REACHABLE Forward when not reached

ALL_CALLS Forward all calls

ALL_CONDITIONAL_CALLS Forward all conditional calls

phoneNumber Number where the calls are forwarded.

ccl List of call types. Given as a sequence of the ConnectionClass.

Possible values for one ConnectionClass enumeration type:

VOICE Voice calls

DATA Data calls

FAX Fax calls

ALL All calls

time Time in seconds a reply is waited for if the NO_REPLY forwarding is selected.


4.1.4.22 removeCallForwarding void removeCallForwarding( in CallForwardReason cfr, in ConnectionClassList ccl );

Description: Method call is used for removing the call forwarding services provided by the GSM network. The Nokia 12 module needs to be in the service state when call forwarding is removed.



Possible values of the CallForwardingReason enumeration type:




40/84

Member Description





Possible values for one ConnectionClass enumeration type are:

VOICE Voice calls

DATA Data calls

FAX Fax calls

ALL All calls


4.1.4.23 getCallForwarding void getCallForwarding( in CallForwardReason cfr, out PhoneNumber phoneNumber, out boolean active, in ConnectionClass cl, out short time );

Description: Method call is used for getting the call forwarding service status from the network. The Nokia 12 module needs to be in the service state when the forwarding status is queried. The phone number and active status are returned only when the service is active as a whole. For example, if a query is made using ALL_* values, it is not enough that the call forwarding applies only to the VOICE type.



Possible values of the CallForwardReason enumeration type:





41/84

Member Description



phoneNumber Number where the calls are forwarded.

active Activity status.

Possible values:

TRUE Calls are forwarded

FALSE Calls are not forwarded

cl Call type.

Possible values of the ConnectionClass enumeration type:

VOICE Voice calls

DATA Data calls

FAX Fax calls

ALL All calls

time Time in seconds a reply is waited for if the NO_REPLY forwarding is selected.


4.1.4.24 setFacilityLock void setFacilityLock( in FacilityType ft, in ConnectionClassList ccl, in boolean locked, in string password );

Description: Method call is used for manipulating facility locks.


ft Type of the facility lock.

Possible values of the FacilityType enumeration type:

PHONE_TO_SIM_LOCK

The Nokia 12 module asks for a password when other than the current SIM card is inserted. The Nokia 12 module can remember a certain number of previously used cards and do not require a password when these cards are inserted. This value is also

42/84

Member Description known as the security code.

SIM_LOCK

SIM asks for a password when the Nokia 12 module is powered up and when this command is issued. This value is also known as the PIN code.

BARR_ALL_OUTGOING

All outgoing calls are barred.

BARR_INTERNATIONAL_OUTGOING

All international outgoing calls are barred.

BARR_INTERNATIONAL_OUTGOING_EXC_HOM

All international outgoing calls are barred except to the home country.

BARR_ALL_INCOMING

All incoming calls are barred.

BARR_INCOMING_ROAM

All incoming calls are barred when roaming outside the home country.

BARR_ALL

All services are barred.

FIXED_DIALLING_LOCK

Fixed dialling feature. PIN2 is required if not already given during the current session.

ccl List of call types. These values are valid only with call barring facilities. Given as a sequence of the ConnectionClass.


VOICE Voice calls

DATA Data calls

FAX Fax calls

ALL All calls

locked Lock status.

Possible values:

TRUE Lock is set on

FALSE Lock is set off

password Password for the locking operation.

43/84


InvalidPasswordException

4.1.4.25 getFacilityLock void getFacilityLock( in FacilityType ft, in ConnectionClassList ccl, out boolean active );

Description: Method call is used for retrieving activity status of the chosen facility lock.


ft Type of the facility lock.

Possible values of the FacilityType enumeration type are:

PHONE_TO_SIM_LOCK

The Nokia 12 module asks for a password when other than the current SIM card is inserted. The Nokia 12 module can remember a certain number of previously used cards and do not require a password when they are inserted.

SIM_LOCK

SIM asks for a password when the Nokia 12 module is powered up and when this command is issued.

BARR_ALL_OUTGOING

All outgoing calls are barred.

BARR_INTERNATIONAL_OUTGOING

All international outgoing calls are barred.

BARR_INTERNATIONAL_OUTGOING_EXC_HOME

All international outgoing calls are barred except to the home country.

BARR_ALL_INCOMING

All incoming calls are barred.

BARR_INCOMING_ROAM

All incoming calls are barred when roaming outside the home country.

BARR_ALL

All services are barred.

44/84

Member Description

FIXED_DIALLING_LOCK

Fixed dialling feature. PIN2 is required if not already given during the current session.



VOICE Voice calls

DATA Data calls

FAX Fax calls

ALL All calls

active Lock status.

Possible values:

TRUE Lock is set on

FALSE Lock is set off


4.1.4.26 readPhonebookEntry void readPhonebookEntry( in PhonebookType pbt, in long index, out string text, out PhoneNumber phoneNumber );

Description: Method call is used for reading phonebook entries from the Nokia 12 module memory or SIM card memory. If entries are read from the SIM card memory, a SIM card has to be inserted.


pbt The used phonebook type.

Possible values of the PhonebookType enumeration type:

ME_DIALED_CALLS Dialled calls memory

EMERGENCY_NUMBER Emergency numbers

SIM_FIXDIALLING Fixed dialling numbers

ME_MISSED_CALLS Missed calls memory

45/84

Member Description

ME_PHONEBOOK Phone memory

OWN_NUMBERS Own numbers

ME_RECEIVED_CALLS Received calls memory

SIM_PHONEBOOK SIM memory

index Entry index to be read.

text Text associated with the entry.

phoneNumber Phone number associated with the entry.

See also: PhonebookFailureException

4.1.4.27 findPhonebookEntry void findPhonebookEntry( in PhonebookType pbt, in string text, out PhonebookEntryIndexList pbeil );

Description: Method call is used for finding out indexes for the selected entry. If entries are searched from the SIM card memory, a SIM card has to be inserted.













pbeil List of indexes where the given text was found. Given as a sequence of longs.

46/84


4.1.4.28 editPhonebookEntry void editPhonebookEntry( in PhonebookType pbt, in long index, in string text, in PhoneNumber phoneNumber );

Description: Method call is used for editing phonebook entries in the Nokia 12 module memory or SIM card memory. If entries are edited in the SIM card memory, a SIM card has to be inserted.












index Entry index to be edited.




4.1.4.29 addPhonebookEntry void addPhonebookEntry(in PhonebookType pbt, in string text, in PhoneNumber phoneNumber, out long index );

47/84

Description: Method call is used for adding phonebook entries to the Nokia 12 module memory or SIM card memory. If entries are added to the SIM card memory, a SIM card has to be inserted.














index Index for the added entry.


4.1.4.30 removePhonebookEntry void removePhonebookEntry( in PhonebookType pbt, in long index );

Description: Method call is used for removing entries from the Nokia 12 module memory or SIM card memory. If entries are removed from the SIM card memory, a SIM card has to be inserted.





48/84

Member Description








index Entry index to be removed.


4.1.4.31 getPhonebookSize void getPhonebookSize( in PhonebookType pbt, out long numberOfEntries, out long numberOfUsedEntries, out long numberLength, out long textLength );

Description: Method call is used for obtaining sizes of the selected phonebook types. If the sizes for the SIM card phonebook are inquired, a SIM card has to be inserted.












numberOfEntries Number of all entries in the wanted phonebook.

numberOfUsedEntries Number of used entries in the wanted phonebook.

49/84

Member Description

numberLength Number of characters available for number storing.

textLength Number of characters available for text storing.


4.1.4.32 generateDTMFTones void generateDTMFTones( in string digits );

Description: Method call is used for generating Dual Tone Multi-frequency (DTMF) tones. Only digits are accepted and invalid characters are filtered out from the input. The allowed characters are '1', '2', '3', '4', '5', '6', '7', '8', '9', '0', ‘p’, ‘w', ’ *' and '#'.


digits String of digits that represents the different DTMF tones.


50/84

5 IO INTERFACE DEFINITION


ORB/OA/IDL:IOModule/IOControl:1.0

5.1 IO INTERFACE


5.1.1.1 AnalogAlarmLimits struct AnalogAlarmLimits { PinValue lowLimit; PinValue highLimit; Interval period; };

Description: The AnalogAlarmLimits structure contains information about analog input alarms. An alarm is raised when the voltage of the input pin goes out of the given range (that is, below the low limit or above the high limit).


lowLimit Voltage limit of the low alarm (in mV).

highLimit Voltage limit of the high alarm (in mV).

period Time interval specifying how often the alarm limits are checked.

See also: getInputPinAlarmLimits

setInputPinModeAlarming

5.1.2 Exceptions

5.1.2.1 PinNumberOutOfRange exception PinNumberOutOfRange { };

51/84

Description: Exception is used when the given pin number is invalid. It can be raised by the following method calls: getInputPinMode, getInputPinAlarmLimits, getInputPinAlarmPeriod, setInputPinModeDigital, setInputPinModeAnalog, setInputPinModeAlarming, setInputPinModePeriodical, getInputPinValue, setOutputPinValue, and getOutputPinValue.

See also: getInputPinMode

getInputPinAlarmLimits

getInputPinAlarmPeriod


setInputPinModePeriodical

getInputPinValue

setOutputPinValue

getOutputPinValue

5.1.2.2 PinNumberOutOfRangeList exception PinNumberOutOfRangeList { long first };

Description: Exception is used for indicating that at least one of the given pin numbers was not found. It can be raised by the following method calls: setIOControlObserver, removeIOControlObserver, getInputPinValueList, setOutputPinValueList, and getOutputPinValueList.


first Number of the first pin that was not found.

See also: setIOControlObserver

removeIOControlObserver

getInputPinValueList

52/84

setOutputPinValueList

getOutputPinValueList

5.1.2.3 PinValueOutOfRange exception PinValueOutOfRange { };

Description: Exception is used when the given pin value is invalid. It can be raised by the setOutputPinValue method call.

See also: setOutputPinValue

5.1.2.4 PinValueOutOfRangeList exception PinValueOutOfRangeList{ long first };

Description: Exception is used for indicating that at least one of the given values is invalid. It can be raised by the setOutputPinValueList method call.


first First given value that was invalid.

See also: setOutputPinValueList

5.1.2.5 InvalidPinMode exception InvalidPinMode { };

Description: Exception is used when the given input mode is invalid. It can be raised by the following method calls: getInputPinAlarmLimits, getInputPinAlarmPeriod, setInputPinModeDigital, setInputPinModeAnalog, setInputPinModeAlarming, and setInputPinModePeriodical.

See also: getInputPinAlarmLimits

getInputPinAlarmPeriod

53/84



5.1.2.6 ObserverNotExists exception ObserverNotExists { };

Description: Exception is used when the given observer does not exist. It can be raised by the removeIOControlObserver method call.

See also: removeIOControlObserver

5.1.2.7 LowLimitOutOfRange exception LowLimitOutOfRange { };

Description: Exception is used when the given low limit value is invalid. It can be raised by the setInputPinModeAlarming method call.

See also: setInputPinModeAlarming

5.1.2.8 HighLimitOutOfRange exception HighLimitOutOfRange { };

Description: Exception is used when the given high limit value is invalid. It can be raised by the setInputPinModeAlarming method call.


5.1.2.9 PeriodOutOfRange exception PeriodOutOfRange { };

Description: Exception is used when the given period value is invalid. It can be raised by the setInputPinModeAlarming and setInputPinModePeriodical method calls.

54/84



5.1.2.10 ListsNotEven exception ListsNotEven { };

Description: Exception is used when a method call requires two equal length list parameters, but the lengths of the given lists are not equal. It can be raised by the setOutputPinValueList method call.

See also: setOutputPinValueList

5.1.3 Read only attributes

5.1.3.1 NumberOfInputPins Attribute returns the total number of input pins. All the input pins may not be in use depending on the configuration. For more information on the input pins, refer to the Nokia 12 GSM Module Hardware Integration Manual.

5.1.3.2 NumberOfOutputPins Attribute returns the total number of output pins. All the output pins may not be in use depending on the configuration. For more information on the output pins, refer to the Nokia 12 GSM Module Hardware Integration Manual.

5.2 I/O CONTROL INTERFACE

5.2.1 Method calls

5.2.1.1 setIOControlObserver void setIOControlObserver( in IOControlObserver observer, in PinNumberList pinNumbers );

Description: Method call is used for subscribing input events. When an I/O event occurs, the Nokia 12 module calls the pinStateChanged method of the observer object. An observer can be set to an input pin that is either in digital, analog alarming, or

55/84

analog periodical mode. Refer to the Nokia 12 GSM Module Java IMlet Programming Guide for instructions on how to use the observers.


observer Reference to the I/O control observer object.

pinNumbers List of pins the events of which are subscribed. Given as a sequence of pin numbers.

See also: IOControlObserver


pinStateChanged

PinNumberOutOfRangeList

5.2.1.2 removeIOControlObserver void removeIOControlObserver( in IOControlObserver observer, in PinNumberList pinNumbers );

Description: Method call is used for cancelling the observation of the specified pins. The I/O control observer itself is not removed until the removeIOControlObserver method is called for all observed pins. Refer to the Nokia 12 GSM Module Java IMlet Programming Guide for instructions on how to use the observers.


observer Reference to the I/O control observer object.

pinNumbers List of pins from which observation is unsubscribed. Given as a sequence of pin numbers.

See also: IOControlObserver

setIOControlObserver

PinNumberOutOfRangeList

ObserverNotExists

56/84

5.2.1.3 getInputPinMode PinMode getInputPinMode( in PinNumber pinNumber );

Description: Method call is used for querying the mode of a given input pin.


pinNumber Number of the pin.


PinMode The method call was successful.

The mode can have the following values:

DIGITAL

The pin is digital

ANALOG

The pin is analog

ANALOG_ALARMING

The pin is analog and an event is fired when low or high limits are exceeded or when the pin value returns inside the alarm limits

ANALOG_PERIODICAL

The pin is analog and an event is fired periodically after a certain time

PinNumberOutOfRange The method call was unsuccessful. The pin number is invalid.

See also: PinNumberOutOfRange

5.2.1.4 getInputPinAlarmLimits AnalogAlarmLimits getInputPinAlarmLimits( in PinNumber pinNumber );

Description: Method call is used for querying the alarm limit settings of a given analog input pin.

57/84


pinNumber Number of the pin to be queried.


AnalogAlarmLimits The method call was successful. The alarm limits of the pin are returned.

See also: AnalogAlarmLimits

PinNumberOutOfRange

InvalidPinMode

5.2.1.5 getInputPinAlarmPeriod Interval getInputPinAlarmPeriod( in PinNumber pinNumber );

Description: Method call is used for querying the periodical alarm interval of an analog input pin.




Interval The method call was successful. The interval value (in seconds)of the alarm is returned.


InvalidPinMode

5.2.1.6 setInputPinModeAlarming void setInputPinModeAlarming( in PinNumber pinNumber, in AnalogAlarmLimits limits );

58/84

Description: Method call is used for setting the mode of a given input pin into analog and alarming.

Note: The number of available I/O pins varies depending on the configuration of the Nokia 12 module.


pinNumber Number of the pin to be set.

limits Analog alarming settings for the pin.


InvalidPinMode

LowLimitOutOfRange

HighLimitOutOfRange

5.2.1.7 setInputPinModePeriodical void setInputPinModePeriodical( in PinNumber pinNumber, in Interval interval);

Description: Method call is used for setting the mode of a given input pin into analog and periodical.




interval Interval in seconds when the event is fired.


59/84

InvalidPinMode

PeriodOutOfRange

5.2.1.8 getInputPinValue PinValue getInputPinValue( in PinNumber pinNumber );

Description: Method call is used for querying the value of a given input pin.




PinValue Value of the pin. If the input pin is analog, the returned value is the voltage of the pin in mV. If the input pin is digital, the returned value is 0 (zero) for the Boolean value ‘false’, otherwise ‘true’.


5.2.1.9 getInputPinValueList PinValueList getInputPinValueList( in PinNumberList pinNumbers );

Description: Method call is used for getting multiple input pin values.


pinNumbers Sequence of pin numbers to be queried.


PinValueList Values of the pins. This sequence contains the values of the pins in the same order as they are in the pinNumbers sequence. If the input pin is analog, the returned value is the voltage of the pin in mV. If the input pin is digital, the returned value is 0 (zero) for the

60/84

Value Description Boolean value ‘false’, otherwise ‘true’.

See also: PinNumberOutOfRangeList

5.2.1.10 setOutputPinValue void setOutputPinValue( in PinNumber pinNumber, in PinValue value );

Description: Method call is used to change the value of the given output pin.




value New value for the pin. Value 0 (zero) denotes the Boolean value ‘false’ and value 1 denotes the Boolean value ‘true’.


PinValueOutOfRange

5.2.1.11 setOutputPinValueList void setOutputPinValueList( in PinNumberList pinNumbers, in PinValueList values );

Description: Method call is used for setting the values of multiple output pins.


Members: Value Description

61/84

Value Description

pinNumbers Numbers of the pins to be set.

values This sequence contains the values of the pins in the same order as they are in the pinNumbers sequence. Value 0 (zero) denotes the Boolean value ‘false’ and value 1 denotes the Boolean value ‘true’.


PinValueOutOfRangeList

ListsNotEven

5.2.1.12 getOutputPinValue PinValue getOutputPinValue( in PinNumber pinNumber );

Description: Method call is used for querying the value of the given output pin.




PinValue Value of the pin. The returned value is 0 (zero) for the Boolean value ‘false’, otherwise ‘true’.


5.2.1.13 getOutputPinValueList PinValueList getOutputPinValueList( in PinNumberList pinNumbers );

Description: Method call is used for getting values of multiple output pins.


62/84

Member Description

pinNumbers Numbers of the pins to be queried.


PinValueList Values of the pins. This sequence contains the values of the pins in the same order as they are in the pinNumbers sequence. The returned value is 0 (zero) for the Boolean value ‘false’, otherwise ‘true’.


5.3 IOCONTROLOBSERVER INTERFACE The user must implement this interface to be able to receive I/O observer events from the Nokia 12 module. Refer to the Nokia 12 GSM Module Java IMlet Programming Guide for instructions on how to use the observers.

5.3.1 Method calls

5.3.1.1 pinStateChanged void pinStateChanged( in PinNumber pinNumber, in PinValue value );

Description: Method call is used when an I/O observer is set to the Nokia 12 module and an I/O event is fired. I/O control observers are registered with the setIOControlObserver method call and removed with the removeIOControlObserver method call.


pinNumber Number of the pin of which state was changed.

value Value of the pin of which state was changed. If the pin is analog, the returned value is the voltage of the pin in mV. If the pin is digital, the returned value is 0 (zero) for the Boolean value ‘false’, otherwise ‘true’.

See also: setIOControlObserver

63/84


64/84

6 IMLET SUITE MANAGER INTERFACE DEFINITION


ORB/OA/IDL:SuiteManager:1.0

Refer to the Nokia 12 GSM Module Software Developer's Guide for more information on how to download Imlet Suites.

6.1 DATA STRUCTURES

6.1.1 SuiteInformation struct SuiteInformation { string name; string imletVersion; string vendor; StringArray imletList; string microEditionProfile; string microEditionConfiguration; };

Description: The SuiteInformation data structure contains information on the IMlet Suite. It is used for indicating information that is downloaded to the Nokia 12 module. The SuiteInformation contains the same information that can be found from the manifest or Java™ Application Descriptor (JAD) file included in the IMlet Suite Java Archive (JAR) file.


name Name of the IMlet Suite.

imletVersion Version of the IMlet Suite in string format.

vendor IMlet Suite vendor information.

imletList List of IMlets included in the IMlet Suite.

microEditionProfile Java 2 Micro Edition (J2ME™) profile required by the IMlet Suite (for example “IMP-1.0”).

microEditionConfiguration J2ME configuration required by the IMlet Suite (for example “CLDC-1.0”).

65/84

See also: getInformation

6.2 EXCEPTIONS

6.2.1 LoadException exception LoadException { LoadExceptionReason reason; string description; };

Description: Exception is used for indicating an error in the method calls of the SuiteLoader interface.


reason Reason for error.

Possible values of the LoadExceptionReason enumeration type:

GENERAL_LOAD_EXCEPTION

General exception

LOAD_ERROR

Error during the download procedure

INVALID_PACKET_SIZE

Invalid size for the packet to be downloaded into the target

description Error description in string format.

See also: loadSuitePacket

terminalSuiteLoad

6.2.2 SuiteManagerException exception SuiteManagerException { SuiteManagerExceptionReason reason; string description; };

66/84

Description: Exception is used for indicating an error in the method calls of the IMlet, Suite, or SuiteManager interface.


reason Reason for error.

Possible values of the SuiteManagerExceptionReason enumeration type:

GENERAL_EXCEPTION

General exception

CORBA_EXCEPTION

CORBA error in operation

MEMORY_ERROR

Error in memory handling

VALIDATION_ERROR

Unable to validate data

START_ERROR

Error while starting the IMlet

STOP_ERROR

Error while stopping the IMLet

REMOVE_ERROR

Error while removing the IMlet

PREPARE_ERROR

Error in the prepare procedure while starting the IMlet Suite download

RUNTIME_ERROR

Error while running the IMlet

OUT_OF_MEMORY

Not enough memory for the IMlet Suite

NOT_FOUND

Unable to find the IMlet, IMlet Suite, or active IMlets

ALREADY_EXISTS

IMlet or IMlet Suite already exists

67/84

Member Description

NOT_IMPLEMENTED

Function not implemented

description Error description in string format.

See also: start

stop

getStatus

getName

getSuiteName

Suite interface

SuiteManager interface

6.3 RUNTIMELISTENER INTERFACE The user must implement this interface to monitor the status of the IMlet that is currently running in the Nokia 12 module.

6.3.1 Method calls

6.3.1.1 runtimeEvent void runtimeEvent( in string sourceSuiteName, in string sourceIMletName, in CallerID callerID, in RuntimeEventType event, in string eventDescription );

Description: The Nokia 12 module calls the runtimeEvent method of the RuntimeListener implementation in the customer application that has been registered to listen for that particular runtime event with the setRuntimeListener method. The runtimeEvent call is used for indicating that a runtime event has occurred. Refer to the Nokia 12 GSM Module Java IMlet Programming Guide for instructions on how to use the observers.

68/84


sourceSuiteName Name of the IMlet Suite containing the IMlet that fired the event.

sourceIMletName Name of the IMlet that fired the event.

callerID Unique identification of the Nokia 12 module that fired the event. The callerID is set when setting the RuntimeListener to the Nokia 12 module.

event RuntimeEventType that occurred in the IMlet that fired the event.

The event type can be one of the following values: RT_ACTIVATED = 0x00000001; RT_PAUSED = 0x00000002; RT_STOPPED = 0x00000004;

The RuntimeEventType to be listened can be selected while the RuntimeEventListener is set to the Nokia 12 module.

eventDescription Description of the runtime event in string format.

See also: removeSuite

getSuite

6.4 IMLET INTERFACE IMlet interface is used for controlling and monitoring single IMlets of the IMlet Suite located in the Nokia 12 module.

6.4.1 Method calls

6.4.1.1 start void start(in boolean bForceStart) raises (SuiteManagerException);

Description: Method call is used for starting an IMlet. After a successful start, the IMlet status is ACTIVE.

69/84


bForceStart Flag that indicates whether starting the downloaded IMlet is forced.

If the flag is set to ‘true’ and there is an IMlet currently running, the IMlet is stopped and the downloaded IMlet is started instead. If the flag is set to ‘false’ and there is an IMlet currently running, a SuiteManagerException with a reason START_ERROR is thrown.

See also: getIMlet

SuiteManagerException

stop

getStatus

6.4.1.2 stop void stop() raises (SuiteManagerException);

Description: Method call is used for stopping an IMlet. After a successful stop, the IMlet status is PAUSED.

See also: getIMlet


start

getStatus

6.4.1.3 getStatus IMletStatus getStatus();

Description: Method call returns the status of the specified IMlet.

70/84


IMletStatus Status of the IMlet.

Possible values of the IMletStatus enumeration type:

ERROR Unable to get IMlet status

ACTIVE IMlet is running

PAUSED IMlet is stopped

DESTROYED IMlet is destroyed

See also: start

stop

6.4.1.4 getName string getName();

Description: Method call returns the name of the specified IMlet. This name is unique in the IMlet Suite where the IMlet is included.


string Name of the IMlet.

See also: getIMlet

getIMletNameList

6.4.1.5 getSuiteName string getSuiteName();

Description: Method call returns the name of the IMlet Suite where the IMlet is included.

71/84


string Name of the IMlet Suite where the IMlet is included.

See also: getName

6.5 SUITE INTERFACE The Suite interface is used to handle IMlet Suite information in the Nokia 12 module.

6.5.1 Method calls

6.5.1.1 getIMlet IMlet getIMlet(in string name) raises (SuiteManagerException);

Description: Method call returns an IMlet object reference with a specified name from the IMlet Suite.


name Name of the requested IMlet in the IMlet Suite.


IMlet IMlet object with a specified name.

If the IMlet with the specified name is not found, a SuiteManagerException with a reason NOT_FOUND is thrown.

See also: IMlet interface

getIMletNameList


72/84

6.5.1.2 getIMletNameList StringArray getIMletNameList();

Description: Method call returns a list of IMlet object names (in string format) included in the specified IMlet Suite.


StringArray List of IMlet names in an array of strings. If the IMlet Suite is empty, an empty array is returned.

See also: IMlet interface

6.5.1.3 getInformation SuiteInformation getInformation();

Description: Method call returns a SuiteInformation structure that contains information about the IMlet Suite.


SuiteInformation Information about the IMlet Suite.

See also: SuiteInformation

6.6 SUITELOADER INTERFACE The SuiteLoader interface offers methods to download IMlet Suites to the Nokia 12 module.

6.6.1 Method calls

6.6.1.1 loadSuitePacket void loadSuitePacket( in OctetArray data, in boolean isLastPacket)

73/84

raises (LoadException);

Description: Method call downloads one IMlet Suite JAR data packet to the Nokia 12 module.


data Array of bytes that contains the packet data.

isLastPacket Flag that indicates whether the packet to be downloaded is the last one.

See also: LoadException

6.6.1.2 terminalSuiteLoad void terminateSuiteLoad() raises (LoadException);

Description: Method call terminates the IMlet Suite download procedure. After termination, the IMlet Suite download procedure can be restarted by calling the prepareSuiteLoad method.

Note: This method is not called if the download procedure is successfully completed with sending the last packet in the loadSuitePacket method.

See also: LoadException

loadSuitePacket

6.7 SUITEMANAGER INTERFACE The SuiteManager interface offers methods to start the IMlet Suite download procedure and monitor IMlet Suites in the Nokia 12 module.

74/84

6.7.1 Method calls

6.7.1.1 prepareSuiteLoad SuiteLoader prepareSuiteLoad(in string name, in long suiteSizeInBytes, in boolean overrideExisting) raises (SuiteManagerException);

Description: Method call is used for starting the IMlet Suite download procedure to the Nokia 12 module. Once the method is called, it must be completed either by calling the terminateSuiteLoad of the returned SuiteLoader object, or by calling the loadSuitePacket method with its isLastPacket parameter set to ‘true’. Otherwise, it is not possible to start another IMlet Suite download procedure without resetting the Nokia 12 module.


name Name of the IMlet Suite to be downloaded to the Nokia 12 module. This name should be the same that is initialized in the manifest file included in the IMlet Suite JAR.

suiteSizeInBytes Size of the IMlet Suite (in bytes) to be downloaded to the Nokia 12 module.

If the size exceeds the memory size available in the target Nokia 12 module, a SuiteManagerException with a reason OUT_OF_MEMORY is thrown.

overrideExisting Flag that indicates whether to override an IMlet Suite that already exists in the target Nokia 12 module with the same name.

If the flag is set to ‘false’ and an IMlet Suite with the same name already exists, a SuiteManagerException with a reason ALREADY_EXISTS is thrown.


SuiteLoader Reference to the SuiteLoader object that is used to download IMlet Suite data to the Nokia 12 module

See also: SuiteLoader interface


75/84

6.7.1.2 removeSuite void removeSuite(in string name) raises (SuiteManagerException);

Description: Method call is used for removing a specified IMlet Suite from the Nokia 12 module.


name The name of the IMlet Suite to be removed from the Nokia 12 module.

If an IMlet Suite with the specified name is not found from the Nokia 12 module, a SuiteManagerException with reason NOT_FOUND is thrown.

See also: removeAllSuites

getSuiteNameList


6.7.1.3 getSuite Suite getSuite(in string name) raises (SuiteManagerException);

Description: Method call returns a specified Suite object from the Nokia 12 module.


name Name of the IMlet Suite to be obtained from the Nokia 12 module.

If an IMlet Suite with the specified name is not found from the Nokia 12 module, a SuiteManagerException with reason NOT_FOUND is thrown.


Suite Reference to the Suite object in the Nokia 12 module.

76/84

See also: getSuiteNameList


6.7.1.4 getSuiteNameList StringArray getSuiteNameList();

Description: Method call returns a list of all IMlet Suite names in the Nokia 12 module. The list contains an array of strings.


StringArray List of IMlet Suite names in the Nokia 12 module. If the Nokia 12 module does not contain any IMlet Suites, an empty string array is returned.

6.7.1.5 getFreeMemory long getFreeMemory();

Description: Method call returns the amount of free memory available for IMlet Suites in the Nokia 12 module.


long Amount of free memory (in kilobytes) available for IMlet Suites in the Nokia 12 module.

6.7.1.6 getMaxPacketSize long getMaxPacketSize();

Description: Method call returns the maximum size of one IMlet Suite data packet to be downloaded to the Nokia 12 module. The packets are loaded using the loadPacket method of the SuiteLoader interface.

77/84


long Maximum size of one packet (in bytes) to be downloaded to the Nokia 12 module.

See also: loadSuitePacket

6.7.1.7 removeAllSuites void removeAllSuites() raises (SuiteManagerException);

Description: Method call removes all IMlet Suites from the Nokia 12 module.

See also: SuiteManagerException

6.7.1.8 getActiveIMlets IMletArray getActiveIMlets() raises (SuiteManagerException);

Description: Method call returns an array of running IMlets in the Nokia 12 module.

Note: Only one IMlet can be running in the Nokia 12 module at a time.


IMletArray An array of IMlet objects that are running in the Nokia 12 module.

If the Nokia 12 module does not contain any active IMlets, an empty array is returned.

See also: SuiteManagerException

6.7.1.9 setRuntimeListener void setRuntimeListener( in RuntimeEventType eventsToListen,

78/84

in CallerID callerID, in RuntimeListener listener )

raises (SuiteManagerException);

Description: Method call sets a RuntimeListener object to the Nokia 12 module for listening to runtime events generated by active IMlets.


eventsToListen RuntimeEventType to be listened to.

RuntimeEventType value is a combination of numbers: RT_ACTIVATED = 0x00000001; RT_PAUSED = 0x00000002; RT_STOPPED = 0x00000004; RT_ALL_EVENTS = 0x0FFFFFFF

callerID Unique identification of the Nokia 12 module for the RuntimeListener object.

This ID is used to identify the specified Nokia 12 module when the same RuntimeListener object listens for events from multiple Nokia 12 modules.

listener RuntimeListener object that receives events generated by the Nokia 12 module. The user must implement the RuntimeListener object.

See also: removeRuntimeListener

RuntimeListener interface


6.7.1.10 removeRuntimeListener void removeRuntimeListener( in RuntimeEventType eventsToRemove, in RuntimeListener listener ) raises (SuiteManagerException);

Description: Method call stops the RuntimeListener object from listening to a specified runtime event from the Nokia 12 module. The RuntimeListener object is set by using the setRuntimeListener method.

79/84


eventsToRemove RuntimeEventType that cannot be listened to.

The RuntimeEventType value is a combination of numbers: RT_ACTIVATED = 0x00000001; RT_PAUSED = 0x00000002; RT_STOPPED = 0x00000004; RT_ALL_EVENTS = 0x0FFFFFFF

listener RuntimeListener object that is set to listen to events in the Nokia 12 module.

See also: setRuntimeListener

RuntimeListener interface


80/84

7 GPS INTERFACE DEFINITION


ORB/OA/IDL:gps/GpsModule:1.0

The Nokia 12 module offers the following data via the GPS Interface Definition:

• Coordinate information (latitude, and longitude)

• Speed vector

• Altitude

• Visible satellites

• Time and date info

7.1 GPSMODULE INTERFACE


7.1.1.1 Coordinate struct Coordinate { coordinate_type type; octet degrees; octet minutes; octet seconds; short milliseconds; };

Description: The Coordinate structure contains information about the coordinates (location).


type Compass point: NORTH, SOUTH, EAST, WEST

degrees Longitude degrees: 0 – 90

Latitude degrees: 0 - 180

minutes 0 – 59

seconds 0 – 59

81/84

Member Description

milliseconds 0 – 999

7.1.1.2 Location struct Location { Coordinate lat; Coordinate lon; };

Description: The Location structure contains information about latitude and longitude.


lat Latitude

lon Longitude

7.1.1.3 Vector struct Vector { short angle; long speed; };

Description: The Vector structure contains information about the speed vector (direction and speed).


angle Angle in degrees: 0 – 359. 0 indicates north increasing clock-wise.

speed Speed in knots: 0 – 999

7.1.1.4 GpsData typedef long altitude; typedef long utctime; struct GpsData { Location position; Vector speed; altitude alt; utctime aquisitionTime; short visibleSatellites; };

82/84

Description: The GpsData structure contains all the available location information stored in the Nokia 12 module.


position Latitude and longitude.

speed Speed vector, angle, and speed in knots.

alt Altitude in meters from the sea level:

-99999 - +99999

aquisitionTime Seconds since 1st January 1970.

visibleSatellites Number of satellites visible to the external GPS device:

0 - 99

7.1.2 Exceptions

7.1.2.1 NoGpsDataAvailableException exception NoGpsDataAvailableException { ErrorReason reason; };

Description: Exception is used for indicating that there is no GPS device connected to the Nokia 12 module.


reason GPS device is NOT_DETECTED.

See also: getGpsData

7.1.3 Method calls

7.1.3.1 getGpsData GpsData getGpsData() raises (NoGpsDataAvailableException);

Description: Method call is used for obtaining location information from the Nokia 12 module.

83/84

84/84

No parameters are used in the method call. An exception is thrown if a GPS device is not connected to the Nokia 12 module.

See also: NoGpsDataAvailableException

nokia 12 gsm module - hmangas.com 12/nokia_12... · gprs general packet radio ... this document is...

Documents