norisdk doc

NORI SDK

Table of Contents

ii

NORI SDK NORI SDK

1 INTRODUCTION .................................................................................................................. 1-1

1.1 What’s Nori? ............................................................................................................... 1-1

1.2 What´s inside? ............................................................................................................ 1-2

1.3 Installation................................................................................................................... 1-3

2 NORI SDK .............................................................................................................................. 2-1

2.1 NoriApp class.............................................................................................................. 2-1 2.1.1 Class Members............................................................................................ 2-2 2.1.2 NoriApp.Connect ......................................................................................... 2-3 2.1.3 NoriApp.Disconnect..................................................................................... 2-3 2.1.4 NoriApp.GetConnectionStatistics ................................................................ 2-3 2.1.5 NoriApp.GetDeviceLockStatus .................................................................... 2-4 2.1.6 NoriApp.GetDeviceStatus............................................................................ 2-4 2.1.7 NoriApp.GetNetworkOperator ..................................................................... 2-5 2.1.8 NoriApp.GetRATParameters ....................................................................... 2-5 2.1.9 NoriApp.GetRATStatus................................................................................ 2-6 2.1.10 NoriApp.GetSignalQuality ........................................................................... 2-7 2.1.11 NoriApp.GetSignalStrength ......................................................................... 2-7 2.1.12 NoriApp.SetRATParameters ....................................................................... 2-8 2.1.13 NoriApp.ShutdownDevice ........................................................................... 2-8 2.1.14 NoriApp.SwitchOnDevice ............................................................................ 2-9 2.1.15 NoriApp.UnlockDevice ................................................................................ 2-9

2.2 _INoriAppEvents interface .......................................................................................... 2-9 2.2.1 Interface members..................................................................................... 2-10 2.2.2 _INoriAppEvents.DeviceStatus ..................................................................2-11 2.2.3 _INoriAppEvents.SignalStrength ................................................................2-11 2.2.4 _INoriAppEvents.RATParameters..............................................................2-11 2.2.5 _INoriAppEvents.RATStatus...................................................................... 2-12

2.3 NoriConnection class................................................................................................ 2-12 2.3.1 Class Properties ........................................................................................ 2-12 2.3.2 NoriConnection.Username ........................................................................ 2-13 2.3.3 NoriConnection.Password......................................................................... 2-13 2.3.4 NoriConnection.APN ................................................................................. 2-14

Table of Contents (Cont.)

iii

2.3.5 NoriConnection.UseDNS........................................................................... 2-14 2.3.6 NoriConnection.PrimaryDNS..................................................................... 2-14 2.3.7 NoriConnection.SecondaryDNS................................................................ 2-14 2.3.8 NoriConnection.PrimaryWINS................................................................... 2-14 2.3.9 NoriConnection.SecondaryWINS.............................................................. 2-15 2.3.10 NoriConnection.UseIPAddress.................................................................. 2-15 2.3.11 NoriConnection.IPAddress ........................................................................ 2-15 2.3.12 NoriConnection.NoAllowPAP .................................................................... 2-15

List of Figures

iv

NORI SDK NORI SDK

Figure 1-1: Nori automation server ......................................................................................... 1-1

Figure 1-2: Actual and future features .................................................................................... 1-3

Figure 2-1: COM architecture................................................................................................... 2-1

Figure 2-2: Receiving events from Nori ................................................................................ 2-10

1-1

1 INTRODUCTION

1.1 What’s Nori? Nori is the name of a SDK created - still in progress - to assist developers in the task of managing 3G/GPRS devices - like monitoring signal strength or establishing a connection -, under Microsoft Windows operating system. The devices supported include PC Cards and 3G USB devices that have been previously homologated by Telefónica Móviles with Escritorio movistar, so they integrated rightly with SDK. The SDK is being developed with the goals that it is easy to use and more importantly that it can be used in a plethora of development languages and technologies by means of the Microsoft COM/OLE Automation architecture. - If the reader is not familiar with these terms please refer to Microsoft MSDN documentation for a profuse introduction-.

Figure 1-1: Nori automation server

By using COM Automation, more recently renamed as just Automation, Nori can be integrated with the more utilized programming languages in the Windows environment: C++, .NET, VisualBasic, scripting languages like javascript, vbscript or python, and so on. Therefore it’s proper to describe Nori SDK as a conjunction of Automation components forming an objects model. Automation components are usually provided with type libraries, which contain metadata about classes, interfaces and other features exposed by the object library.

INTRODUCTION

1-2

1.2 What´s inside? This first SDK is a preliminary version, it has been created for showing potential and testing purposes. The SDK is somewhat small but completely functional. It includes the following features:

• Hardware detection

• Monitoring hardware

• Establishing GPRS/3G connections

• Selecting radio technology access properties: mode and domain

Next versions will keep adding more features. There are a few of them that can be added in a straightforward manner, because they complement what has been done:

• Network operator management:, listing and selecting

• Sending and receiving SMS

• Sending USSD

• Roaming and homezone detection

And there are potential new capabilities in mind whose integration requires a much more important effort as they open new lines in the development process:

• WiFi: Management of hardware, listing networks around, establishing connections, etc.

• Detecting and using LAN connections

INTRODUCTION

1-3

Figure 1-2: Actual and future features

1.3 Installation Nori is provided a .ZIP archive. Uncompress the contents to a folder of your choice and execute the following command within the installation folder so as to register Nori in the system.

nori.exe /regserver Unregistration is done in a similar fashion:

nori.exe /unregserver

2-1

¡Error! No hay texto con el estilo

2 NORI SDK Nori SDK is implemented in the form of an out-of-process COM server. This means that the server is an executable file where its COM objects model has been registered in the system. Any application in the system can instantiate its objects through COM magic: the first time a client instantiates an object from the server the system loads in memory the executable an create the process, from now on COM makes the marshalling of requests and responses between applications and server process spaces. When all references to COM server objects are released the system closes the process server while freeing resources.

Figure 2-1: COM architecture

2.1 NoriApp class Nori main functionality, interaction with 3G devices, is accomplished by the class NoriApp. Applications that use Nori SDK create an instance of NoriApp with COM. Actually, because devices are shared resources in system, there is only one instance of this class; consequently all clients get the same unique instance. This class does the hard work: it detects devices insertions and extractions, it initializes devices and monitors their status. NoriApp uses properly COM event mechanism, known as connection points, to notify client applications whenever there are a relevant events or changes in the state machine. According to COM

NORI SDK

2-2

nomenclature Nori is an events source and client applications are events sinks. Applications can make use of the interface and methods that expose NoriApp to manage devices and connect with them.

2.1.1 Class Members

Member Description

Connect Start procedure to establish a connection

Connect(connection_name as String,connection_data as INoriConnection) as Long

Disconnect Disconnect/abort a connection established/in progress

Disconnect() as Long

GetConnectionStatistics Get traffic statistics from currently established connection

GetConnectionStatistics(bytesSent as Variant,bytesReceived as Variant,duration as Variant) as Long

GetDeviceLockStatus Get SIM lock device status

GetDeviceLockStatus() as nr_dev_lock

GetDeviceStatus Get device status

GetDeviceStatus() as nr_dev_status

GetNetworkOperator Get currently attached network provider

GetNetworkOperator() as String

GetRATParameters Get mode and domain RAT parameters

GetRATParameters(mode as nr_rat_mode,domain as nr_rat_domain) as Long

GetRATStatus Get current RAT status

GetRATStatus() as nr_rat_status

GetSignalQuality Get received signal strength indication <rssi> and channel bit error rate <ber>

GetSignalQuality(rssi as Long,ber as Long) as Long

GetSignalStrength Get received signal strength in range 0-5

GetSignalStrength() as Long

SetRATParameters Select mode and domain RAT parameters

SetRATParameters(mode as nr_rat_mode,domain as nr_rat_domain) as Void

ShutdownDevice Shutdown device

ShutdownDevice() as Long

NORI SDK

2-3

SwitchOnDevice Switch on device when shutdown

SwitchOnDevice() as Long

UnlockDevice Unlock device's SIM

UnlockDevice(lock_type as nr_dev_lock,lockcode as String,lockcode2 as String) as Long

2.1.2 NoriApp.Connect

Start an asyncronous GPRS/3G connection procedure. Applications should process events reporting device status changes.

Connect(connection_name as String,connection_data as INoriConnection) as Long

Return value:

If the function succeeds, the return value is S_OK. If the function fails, the return value is E_FAIL. If there are invalid parameters, returns E_INVALIDARG.

Parameters:

• [in]connection_name as String: name for RAS connection.

• [in]connection_data as INoriConnection: connection data params. See later for INoriConnection description.

2.1.3 NoriApp.Disconnect

Disconnect a established connection or abort a connection procedure in progress.

Disconnect() as Long

Return value:

If the function succeeds, the return value is S_OK. If the function fails, the return value is E_FAIL.

2.1.4 NoriApp.GetConnectionStatistics

Get traffic statistics from currently established connection.

NORI SDK

2-4

GetConnectionStatistics(bytesSent as Variant,bytesReceived as Variant,duration as Variant) as Long

Return value:


Parameters:

• [in, out]bytesSent as Variant: bytes sent through established connection.

• [in, out]bytesReceived as Variant: bytes received through established connection.

• [in, out]duration as Variant: duration of established connection in seconds.

2.1.5 NoriApp.GetDeviceLockStatus

Get SIM lock device status. See type library for nr_dev_lock values.

GetDeviceLockStatus() as nr_dev_lock

Return value:

SIM lock device status.

enum nr_dev_lock {

nr_dev_lock_unknown = 0,

nr_dev_lock_unlocked,

nr_dev_lock_sim_error,

nr_dev_lock_pin,

nr_dev_lock_puk,

nr_dev_lock_pin2,

nr_dev_lock_puk2

} nr_dev_lock;

2.1.6 NoriApp.GetDeviceStatus

Get device status. See type library for nr_dev_status values.

NORI SDK

2-5

GetDeviceStatus() as nr_dev_status

Return value:

Device status.

enum nr_dev_status {

nr_dev_status_no_device = 0,

nr_dev_status_initializing,

nr_dev_status_locked,

nr_dev_status_searching,

nr_dev_status_connecting,

nr_dev_status_authenticating,

nr_dev_status_connected,

nr_dev_status_idle,

nr_dev_status_shutdown,

nr_dev_status_device_error,

nr_dev_status_device_suspended

} nr_dev_status;

2.1.7 NoriApp.GetNetworkOperator

Get name of currently attached network provider.

GetNetworkOperator() as String

Return value:

Network operator name.

2.1.8 NoriApp.GetRATParameters

Get mode and domain Radio Access Technology parameters as set on device. See type library for nr_rat_mode and nr_rat_domain values.

NORI SDK

2-6

GetRATParameters(mode as nr_rat_mode,domain as nr_rat_domain) as Long

Return value:


Parameters:

• [in, out]mode as nr_rat_mode

enum nr_rat_mode {

nr_rat_mode_gsm = 0,

nr_rat_mode_wcdma,

nr_rat_mode_gsm_first,

nr_rat_mode_wcdma_first,

nr_rat_mode_no_change,

nr_rat_mode_auto,

nr_rat_mode_no_value

} nr_rat_mode;

• [in, out]domain as nr_rat_domain

enum nr_rat_domain {

nr_rat_domain_cs = 0,

nr_rat_domain_ps,

nr_rat_domain_cs_ps,

nr_rat_domain_any,

nr_rat_domain_no_change,

nr_rat_domain_no_value

} nr_rat_domain;

2.1.9 NoriApp.GetRATStatus

Get Radio Access Technology status as a combination of mode and domain values for currently attched network. See type library for nr_rat_status values.

NORI SDK

2-7

GetRATStatus() as nr_rat_status

Return value:

RAT status.

enum nr_rat_status {

nr_rat_status_searching =0,

nr_rat_status_wcdma_cs,

nr_rat_status_wcdma_ps,

nr_rat_status_wcdma_cs_ps,

nr_rat_status_gsm_cs,

nr_rat_status_gsm_ps,

nr_rat_status_gsm_cs_ps,

nr_rat_status_no_value

} nr_rat_status;

2.1.10 NoriApp.GetSignalQuality

Get received signal strength indication <rssi> and channel bit error rate <ber> as returned by device.

GetSignalQuality(rssi as Long,ber as Long) as Long

Return value:


Parameters:

• [in, out]rssi as Long: signal strength indication in dbm. 99 not known or not detectable.

• [in, out]ber as Long: channel bit error rate (in percent). 99 not known or not detectable.

2.1.11 NoriApp.GetSignalStrength

Get received signal strength.

NORI SDK

2-8

GetSignalStrength() as Long

Return value:

Signal strength in range [0-5].

2.1.12 NoriApp.SetRATParameters

Select mode and domain Radio Access Technology parameters on current device. See type library for nr_rat_mode and nr_rat_domain values.

SetRATParameters(mode as nr_rat_mode,domain as nr_rat_domain) as Long

Return value:


Parameters:

• [in, out]mode as nr_rat_mode.

• [in, out]domain as nr_rat_domain.

2.1.13 NoriApp.ShutdownDevice

Shutdown device and release any device port opened.


Return value:


NORI SDK

2-9

2.1.14 NoriApp.SwitchOnDevice

Switch on device. Nori switchs on automatically the device when it detects one, so there is only need to call this method if you previously have called ShutdownDevice().


Return value:


2.1.15 NoriApp.UnlockDevice

Unlock device's SIM. See type library for nr_dev_lock values.

UnlockDevice(lock_type as nr_dev_lock,lockcode as String,lockcode2 as String) as Long

Return value:


Parameters:

• [in]lock_type as nr_dev_lock: type of lock to be unlocked.

• [in]lockcode as String: lock code, such as SIM PIN.

• [in]lockcode2 as String: used for locks that required two codes. For example: if lock_type is SIM PUK, then lockcode is PUK and lockcode2 is new PIN.

2.2 _INoriAppEvents interface Nori avoids client from tedious polling notifying important events, which is a quite more efficient and elegant solution. Applications that want to receive events from Nori have to provide an implementation for the interface _INoriAppEvents (see later). To establish the link between source - Nori - and sinks - implementation of event interface -, clients have to use IConnetionPointContainer and IConnectionPoint standard COM interfaces. Some languages scripts somewhat hide COM from developers, runtime sinks can be handled in a

NORI SDK

2-10

more comfortable way. For example, vbscript interpreters transparently create the sinks and developers only have to provide events handlers.

Figure 2-2: Receiving events from Nori

2.2.1 Interface members Member Description

DeviceState Notify device state change

DeviceState(status as nr_dev_status) as Long

SignalStrength Notify signal stregth change

SignalStrength(strength as Long) as Long

RATParameters Notify RAT parameters change

RATParameters(mode as nr_rat_mode, domain as nr_rat_domain) as Long

RATStatus Notify RAT status change

RATStatus(status as nr_rat_status) as Long

NORI SDK

2-11

2.2.2 _INoriAppEvents.DeviceStatus

Notify clients applications of a change in device status. See type library for nr_dev_status values.

DeviceStatus(status as nr_dev_status) as Long

Return value:

Anything, no matter.

Parameters:

• [in]status as nr_dev_long: new device state.

2.2.3 _INoriAppEvents.SignalStrength

Notify clients applications of a change in signal strength.

SignalStrength(strength as Long) as Long

Return value:


Parameters:

• [in]strength as Long: new received signal strength in range [0-5].

2.2.4 _INoriAppEvents.RATParameters

Notify clients applications of a change in Radio Access Technology parameters. This event is raised by a previous call to SetRATParameters().

See type library for nr_rat_mode and nr_rat_domain values.

RATParameters(mode as nr_rat_mode, domain as nr_rat_domain as Long) as Long

NORI SDK

2-12

Return value:


Parameters:

• [in]mode as nr_rat_mode: new RAT mode.

• [in]domain as nr_rat_domain: new RAT domain.

2.2.5 _INoriAppEvents.RATStatus

Notify clients applications of a change in Radio Access Technology status. See type library for nr_rat_status values.

RATStatus(status as nr_rat_status) as Long

Return value:


Parameters:

• [in]status as nr_rat_status: new RAT status.

2.3 NoriConnection class Class NoriConection is passed as a parameter to method Connect(). Clients going to establish a connection first have to create an object of type NoriConnection, then they fill all the conection properties in and finally they initiate the connection procedure by calling Connect(). Nori internally copies connection properties so the object NoriConection can be released after returning from Connect().

2.3.1 Class Properties

Properties Description

Username Property Username

Username as String

NORI SDK

2-13

Password Property Password

Password as String

APN Property APN

APN as String

UseDNS Property UseDNS

UseDNS as Unsigned Long

PrimaryDNS Property PrimaryDNS

PrimaryDNS as Unsigned Long

SecondaryDNS Property SecondaryDNS

SecondaryDNS as Unsigned Long

PrimaryWINS Property PrimaryWINS

PrimaryWINS as Unsigned Long

SecondaryWINS Property SecondaryWINS

SecondaryWINS as Unsigned Long

UseIPAddress Property UseIPAddress

UseIPAddress as Unsigned Long

IPAddress Property IPAdress

IPAddress as Unsigned Long

NoAllowPAP Property NoAllowPAP

NoAllowPAP as Unsigned Long

2.3.2 NoriConnection.Username

Property Username to authenticate.

Username as String

2.3.3 NoriConnection.Password

Property Password to authenticate.

NORI SDK

2-14

Password as String

2.3.4 NoriConnection.APN

Property Access Point Network.

APN as String

2.3.5 NoriConnection.UseDNS

Property UseDNS. Set to 1 if passing valids values in PrimaryDNS, SecondaryDNS, PrimaryWINS and SecondaryWINS properties. Set to 0 in other case.

UseDNS as Unsigned Long

2.3.6 NoriConnection.PrimaryDNS

Property PrimaryDNS.

PrimaryDNS as Unsigned Long

2.3.7 NoriConnection.SecondaryDNS

Property SecondaryDNS.

SecondaryDNS as Unsigned Long

2.3.8 NoriConnection.PrimaryWINS

Property PrimaryWINS.

NORI SDK

2-15

PrimaryWINS as Unsigned Long

2.3.9 NoriConnection.SecondaryWINS

Property SecondaryWINS.

SecondaryWINS as Unsigned Long

2.3.10 NoriConnection.UseIPAddress

Property UseIPAddress. Set to 1 if passing a valid value in IPAddress property, 0 in other case. If network uses dyanmic IP assignament this value should be 0.

UseIPAddress as Unsigned Long

2.3.11 NoriConnection.IPAddress

Property IPAddress.

IPAddress as Unsigned Long

2.3.12 NoriConnection.NoAllowPAP

Property NoAllowPAP. It´s used to control authenticating protocol. If it’s set to 0 PAP is used, if it’s set to 1 other methods than PAP are used.

NoAllowPAP as Unsigned Long

norisdk doc

Documents