NORI SDK

Table of Contents
ii


NORI SDK NORI SDK
1 INTRODUCTION.................................................................................................................. 1-1
1.1 Whats Nori? ............................................................................................................... 1-1
1.2 Whats 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 Whats 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 Telefnica Mviles 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 its 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 Whats 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,bytesRecei ved 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:
If the function succeeds, the return value is S_OK. If the function fails, the return value is
E_FAIL.

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:
If the function succeeds, the return value is S_OK. If the function fails, the return value is
E_FAIL.

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:
If the function succeeds, the return value is S_OK. If the function fails, the return value is
E_FAIL.

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:
If the function succeeds, the return value is S_OK. If the function fails, the return value is
E_FAIL.

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.

ShutdownDevice() as Long

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

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().

ShutdownDevice() 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.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:
If the function succeeds, the return value is S_OK. If the function fails, the return value is
E_FAIL.

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:
Anything, no matter.

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:
Anything, no matter.

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:
Anything, no matter.

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. Its used to control authenticating protocol. If its set to 0 PAP is
used, if its set to 1 other methods than PAP are used.

NoAllowPAP as Unsigned Long