Developer

Reference
Guide
2.6.0
AT260_DRG_E0

Developer Reference Guide

Contact Information
Forsk (Head Office) 7 rue des Briquetiers
31700 Blagnac
France


L
{

Forsk (USA Office) 200 South Wacker Drive

Suite 3100
Chicago, IL 60606
USA

L
{

Forsk (China Office) Suite 302, 3/F, West Tower,

Jiadu Commercial Building,
No.66 Jianzhong Road,
Tianhe Hi-Tech Industrial Zone,
Guangzhou, 510665,
Peoples Republic of China


L

www.forsk.com
forsk@forsk.com
sales@forsk.com
support@forsk.com
+33 (0) 562 74 72 10
+33 (0) 562 74 72 25
+33 (0) 562 74 72 11

Web
General information
Sales and pricing information
Technical support
General
Technical support
Fax

sales_us@forsk.com
support_us@forsk.com
+1 312 674 4846
+1 888 GoAtoll (+1 888 462 8655)
+1 312 674 4847

Sales and pricing information

Technical support
General
Technical support
Fax

www.forsk.com.cn
enquiries@forsk.com.cn
+86 20 8553 8938
+86 20 8553 8285
+86 10 6513 4559

Web
Information and enquiries
Telephone
Fax (Guangzhou)
Fax (Beijing)

Atoll 2.6.0 Developer Reference Guide Release AT260_DRG_E0

Copyright 1997 - 2007 by Forsk

The software described in this document is provided under a license agreement. The software may only be used/copied
under the terms and conditions of the license agreement. No part of this document may be copied, reproduced or distributed in any form without prior authorisation from Forsk.
The product or brand names mentioned in this document are trademarks or registered trademarks of their respective registering parties.

About Developer Reference Guide

This document contains information on the Atoll Development Kit and APIs. The Developer Reference Guide is aimed at
readers concerned with programming using the Atoll API. This guide describes how to use the Atoll Development Kit and
how to develop interfaces using the APIs. It also provides examples and references for better understanding and in order
to render the reader capable of developing efficient and stable interfaces.
The Developer Reference Guide comprises four chapters. The first chapter is a basic introduction to the Atoll Development
Kit. The next three chapters respectively contain details of three different APIs available, the Propagation API, the General
API, and the AFP API.

Forsk 2007

AT260_DRG_E0

iii

Developer Reference Guide

iv

AT260_DRG_E0

Forsk 2007

Table of Contents

Table of Contents

1
1.1
1.2
1.3
1.3.1
1.3.2
1.3.3
1.3.4
1.3.5
1.3.6

2
2.1
2.2
2.2.1
2.2.2
2.2.3
2.2.4
2.2.5
2.2.6
2.2.7
2.3
2.3.1
2.3.1.1
2.3.1.2
2.3.1.3
2.3.1.4
2.3.2
2.3.2.1
2.3.2.2
2.3.2.2.1
2.3.2.2.2
2.3.2.3
2.3.2.3.1
2.3.2.3.2
2.3.2.4
2.3.2.4.1
2.3.2.4.2
2.3.2.5
2.3.3
2.3.3.1
2.3.3.1.1
2.3.3.1.2
2.3.3.1.3
2.3.3.1.4
2.3.3.1.5
2.3.3.2
2.3.3.2.1
2.3.3.3
2.3.3.3.1
2.3.3.3.2
2.3.3.4
2.3.3.4.1
2.3.3.4.2
2.3.3.4.3
2.3.3.4.4
2.3.3.5
2.3.3.5.1
2.3.3.5.2

Forsk 2007

Introduction ..................................................................................... 19
Getting Started ....................................................................................................................................... 19
Prerequisites .......................................................................................................................................... 19
Supported Extensions ............................................................................................................................ 19
Propagation Models ......................................................................................................................... 19
Add-ins ............................................................................................................................................. 19
Macros.............................................................................................................................................. 20
Scripts .............................................................................................................................................. 20
Automatic Frequency Planning Models ............................................................................................ 20
Mixing Extensions ............................................................................................................................ 20

Propagation API .............................................................................. 23

Propagation Models in Atoll ................................................................................................................... 23
Propagation Model Tutorial .................................................................................................................... 23
Step 1: Creating The Propagation Model Project ............................................................................. 23
Step 2: Adding The Propagation Model ........................................................................................... 24
Step 3: Returning Meaningful Errors ................................................................................................ 25
Step 4: Adding Properties ................................................................................................................ 25
Step 5: Adding a Property Page ....................................................................................................... 27
Step 6: Adding Persistence .............................................................................................................. 30
Step 7: Adding Notifications ............................................................................................................. 31
Reference Guide .................................................................................................................................... 31
Structures ......................................................................................................................................... 32
Polarization ................................................................................................................................. 32
Pixel_Type .................................................................................................................................. 32
Extraction_Mode......................................................................................................................... 32
Geopoint and Georect Structures ............................................................................................... 32
Model Interfaces............................................................................................................................... 32
Used COM Interfaces ................................................................................................................. 33
IPropagationModel Interface....................................................................................................... 33
IPropagationModel::CalculateGrid Method ........................................................................... 33
IPropagationModel::CalculatePoints Method ........................................................................ 34
IMultiResPropagationModel Interface......................................................................................... 35
IMultiResPropagationModel::CalculateGrids Method ........................................................... 35
CalculateGrids Implementation Example .............................................................................. 35
IOnProfilePropagationModel and IOnProfilePropagationModel2 Interfaces............................... 38
IOnProfilePropagationModel::CalculateProfile Method......................................................... 38
IOnProfilePropagationModel2::ShowDetails Method ............................................................ 39
ITransmitterAntennaLossesNotIncluded Interface...................................................................... 39
Atoll Interfaces.................................................................................................................................. 40
IRasterGeoData Interface........................................................................................................... 40
IRasterGeoData::GetBoundingBox Method .......................................................................... 40
IRasterGeoData::GetGridResolution Method........................................................................ 41
IRasterGeoData::ExtractProfile Method................................................................................ 41
IRasterGeoData::GetValue Method ...................................................................................... 41
IRasterGeoData::PrepareFastAccessData Method .............................................................. 42
IMultiGridData Interface.............................................................................................................. 42
IMultiGridData::EnumDataSet Method.................................................................................. 42
IClutterInfo Interface ................................................................................................................... 43
IClutterInfo::GetCount Method .............................................................................................. 43
IClutterInfo::GetItemProperties Method ................................................................................ 43
IEnumGridData Interface ............................................................................................................ 43
IEnumGridData::Next Method ............................................................................................... 44
IEnumGridData::Skip Method ............................................................................................... 44
IEnumGridData::Reset Method ............................................................................................. 44
IEnumGridData::Clone Method ............................................................................................. 44
IGridData Interface ..................................................................................................................... 45
IGridData::GetDimension Method ......................................................................................... 45
IGridData::GetPixelType Method .......................................................................................... 45
AT260_DRG_E0

Developer Reference Guide

2.3.3.5.3
2.3.3.6
2.3.3.6.1
2.3.3.6.2
2.3.3.6.3
2.3.3.6.4
2.3.3.6.5
2.3.3.6.6
2.3.3.6.7
2.3.3.6.8
2.3.3.6.9
2.3.3.6.10
2.3.3.6.11
2.3.3.6.12
2.3.3.6.13
2.3.3.7
2.3.3.7.1
2.3.3.8
2.3.3.8.1
2.3.3.8.2
2.3.3.8.3
2.3.3.9
2.3.3.9.1
2.3.3.9.2
2.3.3.10
2.3.3.10.1
2.3.3.10.2
2.3.3.10.3
2.3.3.10.4
2.3.3.10.5
2.3.3.10.6
2.3.3.11
2.3.3.11.1
2.3.3.11.2
2.3.3.11.3
2.3.3.11.4
2.3.3.12
2.3.3.12.1
2.3.3.12.2
2.3.3.12.3
2.3.3.12.4
2.3.3.13
2.3.3.13.1
2.3.3.13.2
2.3.3.13.3
2.3.3.13.4
2.3.3.14
2.3.3.14.1
2.3.3.14.2
2.3.3.14.3
2.3.3.14.4
2.3.3.14.5
2.3.3.14.6
2.3.3.15
2.3.3.15.1
2.3.3.15.2
2.3.3.15.3
2.3.3.15.4
2.3.3.15.5
2.3.4
2.3.4.1
2.3.4.2
2.3.4.3
2.3.4.4
2.3.4.5
2.3.4.6
2.3.4.7
2.3.4.8

vi

IGridData::ExtractSubGrid Method ........................................................................................46

IRadioTransmitter, IRadioTransmitter2 and IRadioTransmitter3 Interfaces ................................46
IRadioTransmitter::GetHeight Method ...................................................................................47
IRadioTransmitter::GetAltitude Method .................................................................................47
IRadioTransmitter::GetAzimut Method ..................................................................................47
IRadioTransmitter::GetTilt Method.........................................................................................47
IRadioTransmitter::GetFrequency Method ............................................................................47
IRadioTransmitter::GetLocation Method................................................................................48
IRadioTransmitter::GetPolarization Method...........................................................................48
IRadioTransmitter::GetAntennaLoss Method ........................................................................48
IRadioTransmitter::GetCalculationZone Method ...................................................................48
IRadioTransmitter2::GetTransmitterId Method ......................................................................49
IRadioTransmitter2::GetEirp Method .....................................................................................49
IRadioTransmitter2::GetFieldValue Method ..........................................................................49
IRadioTransmitter3::EnumAntennas Method.........................................................................50
IRadioReceiver Interface.............................................................................................................50
IRadioReceiver::GetHeight Method .......................................................................................50
IProgressCallback, IProgressCallback2 and IProgressCallback3 Interfaces ..............................51
IProgressCallback::OnProgress Method ...............................................................................51
IProgressCallback2::SetStatusText Method ..........................................................................51
IProgressCallback3::LogEvent Method .................................................................................51
IMultiResolution Interface ............................................................................................................52
IMultiResolution::GetCount Method.......................................................................................52
IMultiResolution::GetResolution Method ...............................................................................52
IMeasurements Method...............................................................................................................52
IMeasurements::GetName Method........................................................................................53
IMeasurements::GetTransmitter Method ...............................................................................53
IMeasurements::GetReceptionHeight Method.......................................................................53
IMeasurements::GetCount Method........................................................................................53
IMeasurements::GetLocations Method..................................................................................53
IMeasurements::GetMeasurements Method .........................................................................54
IEnumMeasurements Interface ...................................................................................................54
IEnumMeasurements::Next Method ......................................................................................54
IEnumMeasurements::Skip Method.......................................................................................55
IEnumMeasurements::Reset Method ....................................................................................55
IEnumMeasurements::Clone Method ....................................................................................55
IMeasurementsCatalog Interface ................................................................................................55
IMeasurementsCatalog::EnumMeasurements Method .........................................................55
IEnumGridData::Skip Method ................................................................................................56
IEnumGridData::Reset Method..............................................................................................56
IEnumGridData::Clone Method..............................................................................................56
IAntenna Interface .......................................................................................................................56
IAntenna::GetFieldValue Method...........................................................................................57
IAntenna::GetSectionCount Method ......................................................................................57
IAntenna::GetSection Method................................................................................................57
Example.................................................................................................................................58
IAntennaPatternSection Interface ...............................................................................................60
_IAntennaPatternValue Structure ..........................................................................................61
TypeDefs ...............................................................................................................................61
Enumerations.........................................................................................................................61
IAntennaPatternSection::GetOrientation Method ..................................................................61
IAntennaPatternSection::GetPatternSize Method .................................................................61
IAntennaPatternSection::GetPattern Method ........................................................................61
IEnumAntennas Interface............................................................................................................62
Example.................................................................................................................................62
IEnumAntennas::Next Method...............................................................................................62
IEnumAntennas::Skip Method ...............................................................................................62
IEnumAntennas::Reset Method.............................................................................................63
IEnumAntennas::Clone Method.............................................................................................63
Coding Rules.....................................................................................................................................63
Serialization of All Parameters (Multithread) ...............................................................................63
Global Variables (Multithread) .....................................................................................................63
Read Access to External Files (Distributed Computing) .............................................................63
Performance (Multithread)...........................................................................................................63
Use of GetFieldValue Method (Multithread) ................................................................................63
Only One Thread for Calculations (Multithread) ..........................................................................64
Log File Generation (Multithread)................................................................................................64
Interaction with Add-Ins (Multithread)..........................................................................................64
AT260_DRG_E0

Forsk 2007

Table of Contents

3
3.1
3.2
3.2.1
3.2.2
3.2.2.1
3.2.2.2
3.2.2.3
3.2.3
3.2.4
3.3
3.3.1
3.3.2
3.3.3
3.3.4
3.3.5
3.4
3.4.1
3.4.2
3.4.3
3.5
3.5.1
3.5.1.1
3.5.1.2
3.5.1.3
3.5.2
3.5.3
3.5.4
3.5.5
3.5.6
3.5.7
3.5.8
3.5.8.1
3.5.8.1.1
3.5.8.1.2
3.5.8.1.3
3.5.8.1.4
3.5.8.1.5
3.5.8.1.6
3.5.8.1.7
3.5.8.1.8
3.5.8.1.9
3.5.8.1.10
3.5.8.1.11
3.5.8.1.12
3.5.8.1.13
3.5.8.1.14
3.5.8.1.15
3.5.8.1.16
3.5.8.2
3.5.8.2.1
3.5.8.2.2
3.5.8.2.3
3.5.8.2.4
3.5.8.2.5
3.5.8.2.6
3.5.8.2.7
3.5.8.2.8
3.5.8.2.9
3.5.8.2.10
3.5.8.3
3.5.8.3.1
3.5.8.3.2
3.5.8.3.3
3.5.8.3.4
3.5.8.3.5
3.5.8.3.6

Forsk 2007

General API .................................................................................... 67

Add-ins, Macros, and Scripts ................................................................................................................. 67
Add-in Tutorial........................................................................................................................................ 67
Step 1: Creating the Add-in Project.................................................................................................. 67
Step 2: Inserting and Configuring the Add-in Object ........................................................................ 68
Commands ................................................................................................................................. 70
Events......................................................................................................................................... 70
Connection.................................................................................................................................. 70
Step 3: Catching Events................................................................................................................... 71
Step 4: Customizing Add-ins ............................................................................................................ 72
Script Tutorial ......................................................................................................................................... 72
Step 1: Writing a VBScript File ......................................................................................................... 72
Step 2: Testing the Script ................................................................................................................. 73
Step 3: Scheduling the Script ........................................................................................................... 73
Step 4: Debugging the Script ........................................................................................................... 75
Step 5: Error Management ............................................................................................................... 75
Macro Tutorial ........................................................................................................................................ 77
Adding Macros in Atoll...................................................................................................................... 77
Running a Macro .............................................................................................................................. 78
Saving a List of Macros .................................................................................................................... 78
Reference Guide .................................................................................................................................... 78
Atoll Object Model ............................................................................................................................ 79
Objects........................................................................................................................................ 79
Properties and Methods.............................................................................................................. 79
Global or Member Access Functions.......................................................................................... 80
Application Object ............................................................................................................................ 80
Documents Object ............................................................................................................................ 81
Document Object.............................................................................................................................. 81
TabularData Object .......................................................................................................................... 82
ChildFolder Object............................................................................................................................ 84
CoordSystem Object ........................................................................................................................ 84
Atoll Interfaces.................................................................................................................................. 85
IApplication Interface .................................................................................................................. 86
Application Property .............................................................................................................. 87
Parent Property ..................................................................................................................... 87
Active Property...................................................................................................................... 87
Documents Property ............................................................................................................. 87
Name Property ...................................................................................................................... 88
FullName Property ................................................................................................................ 88
Path Property ........................................................................................................................ 88
ActiveDocument Property ..................................................................................................... 89
WindowStatus Property ........................................................................................................ 89
StatusBar Property................................................................................................................ 90
Visible Property ..................................................................................................................... 90
Version Property ................................................................................................................... 91
Quit Method .......................................................................................................................... 91
LogMessage Method ............................................................................................................ 91
SetAddinInfo Method ............................................................................................................ 91
AddCommand Method .......................................................................................................... 92
IDocuments Interface.................................................................................................................. 92
_NewEnum Property ............................................................................................................. 92
Count Property ...................................................................................................................... 93
Item Property ........................................................................................................................ 94
Application Property .............................................................................................................. 94
Parent Property ..................................................................................................................... 94
Open Method ........................................................................................................................ 94
Add Method........................................................................................................................... 95
OpenFromDatabase Method ................................................................................................ 96
CloseAll Method .................................................................................................................... 97
SaveAll Method ..................................................................................................................... 97
IDocument Interface ................................................................................................................... 97
Application Property .............................................................................................................. 99
Parent Property ..................................................................................................................... 99
FullName Property ................................................................................................................ 99
Name Property ...................................................................................................................... 99
Path Property ...................................................................................................................... 100
ReadOnly Property ............................................................................................................. 100

AT260_DRG_E0

vii

Developer Reference Guide

3.5.8.3.7
3.5.8.3.8
3.5.8.3.9
3.5.8.3.10
3.5.8.3.11
3.5.8.3.12
3.5.8.3.13
3.5.8.3.14
3.5.8.3.15
3.5.8.3.16
3.5.8.3.17
3.5.8.3.18
3.5.8.3.19
3.5.8.3.20
3.5.8.3.21
3.5.8.3.22
3.5.8.3.23
3.5.8.3.24
3.5.8.3.25
3.5.8.3.26
3.5.8.3.27
3.5.8.4
3.5.8.4.1
3.5.8.4.2
3.5.8.5
3.5.8.5.1
3.5.8.6
3.5.8.6.1
3.5.8.6.2
3.5.8.6.3
3.5.8.6.4
3.5.8.6.5
3.5.8.7
3.5.8.7.1
3.5.8.8
3.5.8.8.1
3.5.8.8.2
3.5.8.8.3
3.5.8.8.4
3.5.8.8.5
3.5.8.8.6
3.5.8.8.7
3.5.8.8.8
3.5.8.8.9
3.5.8.8.10
3.5.8.8.11
3.5.8.8.12
3.5.8.8.13
3.5.8.8.14
3.5.8.8.15
3.5.8.8.16
3.5.8.8.17
3.5.8.8.18
3.5.8.8.19
3.5.8.9
3.5.8.9.1
3.5.8.9.2
3.5.8.9.3
3.5.8.9.4
3.5.8.9.5
3.5.8.9.6
3.5.8.9.7
3.5.8.9.8
3.5.8.9.9
3.5.8.9.10
3.5.8.9.11
3.5.8.10
3.5.8.10.1

viii

Saved Property ....................................................................................................................100

CoordSystemProjection Property ........................................................................................100
CoordSystemDisplay Property.............................................................................................101
CoordSystemInternal Property ............................................................................................101
TransmissionUnit Property ..................................................................................................101
ReceptionUnit Property........................................................................................................101
DistanceUnit Property..........................................................................................................102
Close Method.......................................................................................................................102
FilePrint Method...................................................................................................................102
Save Method........................................................................................................................102
Refresh Method ...................................................................................................................103
Archive Method....................................................................................................................103
Run Method .........................................................................................................................103
SetConfig Method ................................................................................................................104
Import Method......................................................................................................................104
GetRecords Method.............................................................................................................104
Redraw Method ...................................................................................................................105
CenterMapOn Method .........................................................................................................105
GetRootFolder Method ........................................................................................................105
GetSortedSignals Method....................................................................................................106
GetSortedServers Method ...................................................................................................107
IDocument2 Interface ................................................................................................................108
RunPathloss Method ...........................................................................................................108
GetService Property ............................................................................................................108
IDocument3 Interface ................................................................................................................109
ExportConfig Method ...........................................................................................................109
IDocument4 Interface ................................................................................................................109
GetCommandDefaults Property...........................................................................................110
InvokeCommand Property ...................................................................................................110
RadiatedPowerUnit Property ...............................................................................................110
AntennaGainUnit Property...................................................................................................110
HeightOffsetUnit Property....................................................................................................111
IResultFileProvider Interface .....................................................................................................111
Build Method........................................................................................................................111
ITabularData Interface...............................................................................................................112
ColumnCount Property ........................................................................................................112
RowCount Property .............................................................................................................112
Edit Method..........................................................................................................................113
AddNew Method ..................................................................................................................113
Update Method ....................................................................................................................113
Delete Method .....................................................................................................................113
GetValue Method.................................................................................................................114
SetValue Method .................................................................................................................115
GetPrimaryKey Method .......................................................................................................117
FindPrimaryKey Method ......................................................................................................117
Find Method.........................................................................................................................117
GetFormattedValue Method ................................................................................................118
Reading Pathloss Matrices ..................................................................................................118
Editing Computation or Focus Zones ..................................................................................120
Editing Repeaters ................................................................................................................122
Reading Antenna Signatures...............................................................................................122
Accessing Transmitter EIRPs and Antenna Diagrams ........................................................122
Reading Data Tab Folders (Simulations).............................................................................123
Reading Data Tab Folders (CW Measurements and Test Mobile Data) .............................124
ITabularData2 Interface.............................................................................................................125
CancelUpdate Method .........................................................................................................126
ColumnNumber Property .....................................................................................................126
CanEdit Property .................................................................................................................126
CanAddNew Property ..........................................................................................................126
CanFilterSort Property .........................................................................................................126
Filter Property ......................................................................................................................127
Filter Property ......................................................................................................................127
Sort Property........................................................................................................................127
Sort Property........................................................................................................................128
GetOriginalValue Property...................................................................................................128
RowStatus Property.............................................................................................................128
IPropertyContainer Interface .....................................................................................................128
Get Property ........................................................................................................................129
AT260_DRG_E0

Forsk 2007

Table of Contents

3.5.8.10.2
3.5.8.11
3.5.8.11.1
3.5.8.11.2
3.5.8.11.3
3.5.8.11.4
3.5.8.11.5
3.5.8.11.6
3.5.8.11.7
3.5.8.11.8
3.5.8.11.9
3.5.8.11.10
3.5.8.11.11
3.5.8.12
3.5.8.12.1
3.5.8.12.2
3.5.8.12.3
3.5.8.12.4
3.5.8.12.5
3.5.8.12.6
3.5.8.13
3.5.8.13.1
3.5.8.13.2
3.5.8.14
3.5.8.14.1
3.5.8.14.2
3.5.8.14.3
3.5.8.15
3.5.8.15.1
3.5.8.15.2
3.5.8.15.3
3.5.8.15.4
3.5.8.15.5
3.5.8.16
3.5.8.16.1
3.5.8.16.2
3.5.8.16.3
3.5.8.16.4
3.5.8.16.5
3.5.8.16.6
3.5.8.17
3.5.8.17.1
3.5.8.17.2
3.5.8.17.3
3.5.8.17.4
3.5.8.17.5
3.5.8.17.6
3.5.8.17.7
3.5.8.17.8
3.5.8.17.9
3.5.8.17.10
3.5.8.17.11
3.5.8.17.12
3.5.8.17.13
3.5.8.17.14
3.5.8.18
3.5.8.18.1
3.5.8.18.2
3.5.8.18.3
3.5.8.18.4
3.5.8.19
3.5.8.19.1
3.5.8.19.2
3.5.8.19.3
3.5.8.20
3.5.8.20.1
3.5.8.20.2
3.5.8.21

Forsk 2007

Set Property ........................................................................................................................ 129

IChildFolder Interface ............................................................................................................... 129
Application Property ............................................................................................................ 130
Parent Property ................................................................................................................... 130
Name Property .................................................................................................................... 130
Count Property .................................................................................................................... 131
Item Property ...................................................................................................................... 131
_NewEnum Property ........................................................................................................... 131
Visible Property ................................................................................................................... 132
Selected Property ............................................................................................................... 132
Export Method..................................................................................................................... 133
CentreOnMap Method ........................................................................................................ 133
Redraw Method................................................................................................................... 134
IChildFolder2 Interface ............................................................................................................. 134
AddChild Property ............................................................................................................... 134
Remove Method.................................................................................................................. 134
Position Property................................................................................................................. 135
Object Property ................................................................................................................... 135
Dispatch Property ............................................................................................................... 135
ObjectKind Property ............................................................................................................ 135
IChildFolder3 Interface ............................................................................................................. 136
GetProperty Property .......................................................................................................... 136
SetProperty Method ............................................................................................................ 137
IClutter Interface ....................................................................................................................... 137
Source Property .................................................................................................................. 137
ClassAttributes Property ..................................................................................................... 137
DefaultAttributes Property ................................................................................................... 138
ISimulationsGroup Interface ..................................................................................................... 138
Source Property .................................................................................................................. 139
Statistics Property ............................................................................................................... 139
MeanSimulation Property.................................................................................................... 139
StdDevSimulation Property ................................................................................................. 139
Example .............................................................................................................................. 140
ISimulation Interface ................................................................................................................. 140
Source Property ................................................................................................................. 140
Statistics Property ............................................................................................................... 140
Cells Property ..................................................................................................................... 140
Sites Property ..................................................................................................................... 140
Mobiles Property ................................................................................................................. 141
Example .............................................................................................................................. 141
IDispCoordSystem Interface..................................................................................................... 141
Code Property ..................................................................................................................... 141
ConvertCoordsTo Method................................................................................................... 142
Datum Property ................................................................................................................... 144
DatumName Property ......................................................................................................... 144
Description Property ........................................................................................................... 144
Ellipsoid Property ................................................................................................................ 145
EllipsoidName Property....................................................................................................... 145
Name Property .................................................................................................................... 145
Pick Method ........................................................................................................................ 145
ProjMethod Property ........................................................................................................... 146
ProjParameter Property ...................................................................................................... 146
SetDatum Method ............................................................................................................... 147
SetProjection Method.......................................................................................................... 147
Unit Property ....................................................................................................................... 147
IApplicationKeyRef Interface .................................................................................................... 148
IsFixedKey Method ............................................................................................................. 148
IsNetworkKey Method ......................................................................................................... 148
GetFskKeyRef Method........................................................................................................ 149
Example .............................................................................................................................. 149
ITraffic Interface........................................................................................................................ 149
Source Property .................................................................................................................. 150
ScenarioProvider Property .................................................................................................. 150
Example .............................................................................................................................. 150
ITrafficScenarioProvider Interface ............................................................................................ 151
GetMeanSize Property........................................................................................................ 151
Create Property................................................................................................................... 151
ITrafficPerEnvironment Interface .............................................................................................. 152
AT260_DRG_E0

ix

Developer Reference Guide

3.5.8.21.1
3.5.8.21.2
3.5.8.21.3
3.5.9
3.5.9.1
3.5.9.1.1
3.5.9.1.2
3.5.9.1.3
3.5.9.1.4
3.5.9.1.5
3.5.9.1.6
3.5.9.1.7
3.5.9.1.8
3.5.9.1.9
3.5.9.1.10
3.5.9.1.11
3.5.9.1.12
3.5.9.1.13
3.5.9.1.14
3.5.9.2
3.5.9.2.1
3.5.9.2.2
3.5.9.2.3
3.5.9.2.4
3.5.10
3.5.10.1
3.5.10.2
3.5.10.3
3.5.10.3.1
3.5.10.3.2
3.5.10.4
3.5.11
3.5.11.1
3.5.11.2
3.5.11.3
3.5.11.4
3.5.11.5
3.5.11.6
3.5.11.7
3.5.11.8
3.5.11.9
3.5.11.10
3.5.11.11
3.5.11.12
3.5.11.13
3.5.11.14
3.5.11.15
3.5.11.16
3.5.11.17
3.5.11.18
3.5.11.19
3.5.12
3.5.12.1
3.5.12.1.1
3.5.12.1.2
3.5.12.1.3
3.5.12.1.4
3.5.12.1.5
3.5.12.2
3.5.12.3
3.5.12.3.1
3.5.12.3.2
3.5.12.3.3
3.5.12.3.4
3.5.12.3.5
3.5.12.4
3.5.12.4.1
3.5.12.4.2

Source Property...................................................................................................................152
ClassAttributes Property ......................................................................................................152
DefaultAttributes Property....................................................................................................152
Outgoing Interfaces.........................................................................................................................155
_IApplicationEvents Interface ....................................................................................................155
WillQuitApp Method .............................................................................................................156
DocumentOpenComplete Method .......................................................................................156
WillCloseDocument Method ................................................................................................156
WillSaveDocument Method .................................................................................................156
DocumentSaveComplete Method........................................................................................156
DocumentNewComplete Method.........................................................................................157
WillRefreshDocument Method .............................................................................................157
RefreshDocumentComplete Method ...................................................................................157
WillArchiveDocument Method..............................................................................................157
ArchiveDocumentComplete Method ....................................................................................157
WillRun Method ...................................................................................................................158
RunComplete Method..........................................................................................................158
LicenceAcquireComplete.....................................................................................................158
LicenceReleaseComplete....................................................................................................159
IAddin Interface .........................................................................................................................159
Connecting an External Tool to a Running Session of Atoll ................................................159
Adding Commands ..............................................................................................................160
OnConnection Method.........................................................................................................160
OnDisconnection Method ....................................................................................................160
Rules, Contracts and Advices .........................................................................................................161
Error Handling ...........................................................................................................................161
Automatic Reference Counting .................................................................................................161
MFC Support Considerations ....................................................................................................161
BSTR and VARIANT Types.................................................................................................161
Resource Access.................................................................................................................161
Shutting Down Atoll ...................................................................................................................161
Enumerations ..................................................................................................................................161
AtoSaveStatus...........................................................................................................................161
AtoSaveChanges ......................................................................................................................161
AtoRefreshPriority .....................................................................................................................162
AtoArchiveStatus .......................................................................................................................162
AtoWindowStatus ......................................................................................................................162
AtoLogType ...............................................................................................................................162
AtoCompareOp .........................................................................................................................162
AtoTransmissionUnit .................................................................................................................162
AtoReceptionUnit ......................................................................................................................163
AtoDistanceUnit.........................................................................................................................163
AtoRadiatedPowerUnit ..............................................................................................................163
AtoAntennaGainUnit..................................................................................................................163
AtoHeightOffsetUnit...................................................................................................................163
AtoRootType .............................................................................................................................163
AtoRowFilter ..............................................................................................................................163
AtoRowStatus............................................................................................................................164
GeographicUnit .........................................................................................................................164
ProjectionMethod ......................................................................................................................164
ProjParameterIndices ................................................................................................................165
Raster Data API ..............................................................................................................................165
Raster Data API Structures .......................................................................................................165
GEOPOINT Structure ..........................................................................................................165
GEOSIZE Structure .............................................................................................................165
GEORECT Structure ...........................................................................................................165
GEOGRID Structure ............................................................................................................166
RASTERBUFFER Structure ................................................................................................166
Enumerations ............................................................................................................................166
IGeoCoverage Interface ............................................................................................................167
get_DataType Method .........................................................................................................167
get_NoDataValue Method ...................................................................................................167
get_BoundingBox Method ...................................................................................................168
get_OptimalResolution Method ...........................................................................................168
Rasterize Method.................................................................................................................168
IGeoRaster Interface .................................................................................................................169
get_Grid Method ..................................................................................................................169
ReadDataBlock Method.......................................................................................................170
AT260_DRG_E0

Forsk 2007

Table of Contents

3.5.12.5
3.5.12.5.1
3.5.12.5.2
3.5.12.6
3.5.12.6.1
3.5.12.6.2
3.5.12.6.3
3.5.12.6.4
3.5.12.7
3.5.12.7.1
3.5.12.7.2
3.5.12.7.3
3.5.12.8
3.6
3.6.1
3.6.2
3.6.3

4
4.1
4.2
4.3
4.3.1
4.3.2
4.3.3
4.3.4
4.3.5
4.3.5.1
4.3.5.1.1
4.3.5.1.2
4.4
4.5
4.5.1
4.5.2
4.5.2.1
4.5.2.2
4.5.2.3
4.5.2.4
4.5.2.5
4.5.2.6
4.5.2.7
4.5.2.8
4.5.2.9
4.5.2.10
4.5.3
4.5.3.1
4.5.3.2
4.5.3.3
4.6
4.6.1
4.6.1.1
4.6.1.2
4.6.1.3
4.6.1.4
4.6.1.5
4.6.1.5.1
4.6.1.6
4.6.1.7
4.6.1.8
4.6.1.9
4.6.2
4.6.2.1
4.6.2.1.1
4.6.2.1.2
4.6.2.1.3
4.6.2.1.4
4.6.2.1.5
4.6.2.2

Forsk 2007

IColorTable Interface ................................................................................................................ 170

get_ColorCount Method ...................................................................................................... 170
get_Colors Method.............................................................................................................. 171
Optional Interfaces For The GeoRaster Object ........................................................................ 171
IActiveMapObject Method ................................................................................................... 171
QueryHitPoint Method......................................................................................................... 171
OnWindowMessage Method ............................................................................................... 171
QueryDataTip Method......................................................................................................... 172
IContextMenu Interface ............................................................................................................ 172
GetCommandString Method ............................................................................................... 173
QueryContextMenu Method ................................................................................................ 173
InvokeCommand Method .................................................................................................... 173
Other Interfaces ........................................................................................................................ 174
Appendix .............................................................................................................................................. 174
Predictions Tabular Data................................................................................................................ 174
Zones Tabular Data........................................................................................................................ 175
Best Signal Export Add-in .............................................................................................................. 175

Basic AFP API .............................................................................. 179

Introduction .......................................................................................................................................... 179
AFP Model Tutorial .............................................................................................................................. 179
Basic Definitions................................................................................................................................... 179
Resource Number .......................................................................................................................... 179
Resource Group ............................................................................................................................. 179
Grouping Scheme .......................................................................................................................... 179
MAL Mobile Allocation List .......................................................................................................... 179
TRG TRX Group.......................................................................................................................... 179
Examples .................................................................................................................................. 180
Normal Cell Configuration ................................................................................................... 180
Concentric Cell Configuration ............................................................................................. 180
Various Roles of Grouping Schemes ................................................................................................... 180
Data Exchange..................................................................................................................................... 180
Nested Interfaces and Arrays as Means ........................................................................................ 180
Elements Implemented by Atoll ...................................................................................................... 181
IAfpNetworkData Interface........................................................................................................ 181
IAssignmentPlan Interface........................................................................................................ 181
IRW_AssignmentPlan:IAssignmentPlan Interface.................................................................... 181
IGroupingScheme Interface...................................................................................................... 181
IDynamicGroupingScheme:IGroupingScheme Interface.......................................................... 181
ITrg Interface ............................................................................................................................ 181
IFrequencyBand Interface ........................................................................................................ 181
ITrgSeparations Interface ......................................................................................................... 181
IInterfMatrix Interface................................................................................................................ 181
IAFPProgress Interface ............................................................................................................ 182
Elements Implemented by The Model ............................................................................................ 182
IAfpModel Interface................................................................................................................... 182
IPlanGenerator Interface .......................................................................................................... 182
IAFPConfigure Interface (Optional) .......................................................................................... 182
Reference Guide .................................................................................................................................. 182
Enumerations and Structures ......................................................................................................... 182
ALLOCATION_TYPE................................................................................................................ 182
ALLOCATION_OPTIONS (Not Used) ...................................................................................... 182
RESOURCE_TYPE .................................................................................................................. 182
ASSIGNMENT_MODE ............................................................................................................. 183
ASSIGNMENT_STATE ............................................................................................................ 183
TO_ASSIGN and FROZEN States...................................................................................... 183
HOPPING_MODE .................................................................................................................... 183
AFP_RELATION_TYPE ........................................................................................................... 183
QUALITY_METRIC (Not Used) ................................................................................................ 184
AFP_BASE_CONFIG ............................................................................................................... 184
Interfaces Implemented by Atoll ..................................................................................................... 184
IAfpNetworkData Interface........................................................................................................ 184
IAfpNetworkData::GetTRGCount Method ........................................................................... 184
IAfpNetworkData::GetFirstTRG Method.............................................................................. 184
IAfpNetworkData::GetTRG Method..................................................................................... 185
IAfpNetworkData::GetSeparations Method ......................................................................... 185
IAfpNetworkData::GetCurrentPlan Method ......................................................................... 185
IAssignmentPlan Interface........................................................................................................ 185
AT260_DRG_E0

xi

Developer Reference Guide

4.6.2.2.1
4.6.2.2.2
4.6.2.2.3
4.6.2.2.4
4.6.2.2.5
4.6.2.2.6
4.6.2.2.7
4.6.2.2.8
4.6.2.3
4.6.2.3.1
4.6.2.3.2
4.6.2.3.3
4.6.2.4
4.6.2.4.1
4.6.2.4.2
4.6.2.4.3
4.6.2.4.4
4.6.2.4.5
4.6.2.5
4.6.2.5.1
4.6.2.5.2
4.6.2.5.3
4.6.2.6
4.6.2.6.1
4.6.2.6.2
4.6.2.6.3
4.6.2.6.4
4.6.2.6.5
4.6.2.6.6
4.6.2.6.7
4.6.2.6.8
4.6.2.6.9
4.6.2.6.10
4.6.2.6.11
4.6.2.6.12
4.6.2.6.13
4.6.2.6.14
4.6.2.6.15
4.6.2.6.16
4.6.2.6.17
4.6.2.6.18
4.6.2.7
4.6.2.7.1
4.6.2.7.2
4.6.2.7.3
4.6.2.8
4.6.2.8.1
4.6.2.8.2
4.6.2.8.3
4.6.2.8.4
4.6.2.9
4.6.2.9.1
4.6.2.9.2
4.6.2.9.3
4.6.2.9.4
4.6.2.9.5
4.6.2.9.6
4.6.2.9.7
4.6.2.9.8
4.6.2.10
4.6.2.10.1
4.6.2.10.2
4.6.2.10.3
4.6.2.10.4
4.6.2.10.5
4.6.2.10.6
4.6.3
4.6.3.1

xii

IAssignmentPlan::GetResource Method..............................................................................185
IAssignmentPlan::GetTrxCount Method ..............................................................................186
IAssignmentPlan::GetTrxNumber Method ...........................................................................186
IAssignmentPlan::GetTrxIndex Method ...............................................................................186
IAssignmentPlan::GetTrxNumbers Method .........................................................................187
IAssignmentPlan::CreateClone Method...............................................................................187
IAssignmentPlan::GetMALScheme Method ........................................................................187
IAssignmentPlan::GetAssignmentState Method..................................................................187
IRW_AssignmentPlan:IAssignmentPlan Interface ....................................................................188
IRW_AssignmentPlan::AddTrxs Method .............................................................................188
IRW_AssignmentPlan::RemoveTrx Method ........................................................................188
IRW_AssignmentPlan::SetResource Method ......................................................................188
IGroupingScheme Interface ......................................................................................................188
IGroupingScheme::GetGroupingSchemeID Method ...........................................................188
IGroupingScheme::GetGroupCount Method .......................................................................189
IGroupingScheme::GetGroupSize Method ..........................................................................189
IGroupingScheme::GetResourceNumbers Method .............................................................189
IGroupingScheme::Contains Method...................................................................................189
IDynamicGroupingScheme: IGroupingScheme Interface .........................................................190
IDynamicGroupingScheme::AddGrp Method ......................................................................190
IDynamicGroupingScheme::SetGrp Method .......................................................................190
IDynamicGroupingScheme::DeleteGrp Method ..................................................................190
ITrg Interface .............................................................................................................................190
ITrg::GetIndx Method...........................................................................................................190
ITrg::GetTrxType Method ....................................................................................................191
ITrg::ContainsBroadcastChannel Method............................................................................191
ITrg::GetGroupingScheme Method......................................................................................191
ITrg::GetFrequencyBand Method ........................................................................................191
ITrg::GetDemand Method ....................................................................................................192
ITrg::GetTrafficLoad Method................................................................................................192
ITrg::GetDLTimeSlotUseRatio Method ................................................................................192
ITrg::GetCostWeightingFactor Method ................................................................................192
ITrg::GetHoppingMode Method ...........................................................................................192
ITrg::GetAssignmentMode Method......................................................................................193
ITrg::GetMALSize Method ...................................................................................................193
ITrg::IsInRelation Method ....................................................................................................193
ITrg::GetTrgRelationCount Method .....................................................................................193
ITrg::GetTrgRelation Method ...............................................................................................194
ITrg::GetTransmitter Method ...............................................................................................194
ITrg::GetQualityThreshold Method ......................................................................................194
ITrg::GetProbabilityThreshold Method.................................................................................194
IFrequencyBand Interface .........................................................................................................195
IFrequencyBand::GetMultiPlexingFactor Method ................................................................195
IFrequencyBand::GetCoherenceBandWidth Method ..........................................................195
IFrequencyBand::GetAdjascentSuppression Method..........................................................195
ITrgSeparations Interface ..........................................................................................................195
ITrgSeparations::GetSeparation Method .............................................................................195
ITrgSeparations::GetDefaultSeparation Method..................................................................196
ITrgSeparations::GetRelationsCount Method......................................................................196
ITrgSeparations::GetRelation Method .................................................................................196
IInterfMatrix Interface ................................................................................................................197
IInterfMatrix::GetHistogramSize Method..............................................................................197
IInterfMatrix::GetInterferingHistogram Method ....................................................................197
IInterfMatrix::GetInterferingProbability Method ....................................................................197
IInterfMatrix::GetInterfererCount Method.............................................................................198
IInterfMatrix::GetInterferers Method.....................................................................................198
IInterfMatrix::GetVictimCount Method..................................................................................198
IInterfMatrix::GetVictims Method .........................................................................................198
IInterfMatrix::GetInterfererHistogram Method ......................................................................199
IAFPProgress Interface .............................................................................................................199
IAFPProgress::StartProgressReport Method.......................................................................199
IAFPProgress::OnProgress Method ....................................................................................199
IAFPProgress::Display Method............................................................................................199
IAFPProgress::DisplayLogInfo Method................................................................................200
IAFPProgress::DisplayLogWarning Method ........................................................................200
IAFPProgress::DisplayLogError Method..............................................................................200
Interfaces Implemented by The Model............................................................................................200
IAfpModel Interface ...................................................................................................................200
AT260_DRG_E0

Forsk 2007

Table of Contents

4.6.3.1.1
4.6.3.2
4.6.3.2.1
4.6.3.2.2
4.6.3.3
4.6.3.3.1
4.7
4.7.1
4.7.2
4.7.3
4.7.4
4.7.5
4.7.6
4.7.6.1
4.7.7
4.7.8
4.7.9
4.7.10

5
5.1
5.2
5.2.1
5.2.2
5.2.3
5.3
5.4
5.4.1
5.5

Forsk 2007

IAfpModel::GetPlanGenerator Method................................................................................ 200

IPlanGenerator Interface .......................................................................................................... 200
IPlanGenerator::Run Method .............................................................................................. 201
IPlanGenerator::Improve Method........................................................................................ 201
IAfpConfigure Interface............................................................................................................. 201
IAfpConfigure::Configure Method ....................................................................................... 201
Using the AFP Interfaces ..................................................................................................................... 202
The Basic main() of an AFP ......................................................................................................... 202
Working with Network Data ............................................................................................................ 203
Access to TRGs ............................................................................................................................. 204
Access to Separations Constraints ................................................................................................ 204
Access to Grouping Schemes ........................................................................................................ 205
Working with Interference Matrices ................................................................................................ 206
Example.................................................................................................................................... 206
Working with Several Assignment Plans ........................................................................................ 206
Reading and Writing Resources..................................................................................................... 208
TRX Manipulations ......................................................................................................................... 209
Specific Case of SFH ..................................................................................................................... 210

Advanced AFP API ....................................................................... 215

Multiple Interface System..................................................................................................................... 215
Read/Write Capabilities and GUI Integration ....................................................................................... 215
New Capabilities............................................................................................................................. 215
Required Implementation ............................................................................................................... 215
IResourceCollection, IAssignmentPlan2, IRW_AssignmentPlan2 Interfaces ................................ 216
Scenarios Support................................................................................................................................ 216
New Services Provided by INetworkData2 .......................................................................................... 216
Temporary Method: INetworkData2::ReadIMFile() ........................................................................ 216
AFP API Code...................................................................................................................................... 216

AT260_DRG_E0

xiii

Developer Reference Guide

xiv

AT260_DRG_E0

Forsk 2007

List of Figures

List of Figures

Figure 2.1:
Figure 2.2:
Figure 2.3:
Figure 2.4:
Figure 2.5:
Figure 2.6:
Figure 2.7:
Figure 2.8:
Figure 3.1:
Figure 3.2:
Figure 3.3:
Figure 3.4:
Figure 3.5:
Figure 3.6:
Figure 3.7:
Figure 3.8:
Figure 3.9:
Figure 3.10:
Figure 3.11:
Figure 3.12:
Figure 3.13:
Figure 3.14:

Forsk 2007

New Project Dialog ....................................................................................................................................

Atoll ATL Project Wizard............................................................................................................................
Add Class Dialog .......................................................................................................................................
Atoll ATL Propagation Model Object Wizard .............................................................................................
Add Property..............................................................................................................................................
Add Property Wizard..................................................................................................................................
Adding a Property Page.............................................................................................................................
ATL Property Page Wizard ........................................................................................................................
New Project Dialog ....................................................................................................................................
Atoll ATL Project Wizard............................................................................................................................
Add Class Dialog .......................................................................................................................................
Atoll ATL Add-in Object Wizard 1 ..............................................................................................................
Atoll ATL Add-in Object Wizard 2 ..............................................................................................................
Add-in Example 1 ......................................................................................................................................
Add-in Example 2 ......................................................................................................................................
Scheduled Tasks Wizard 1 ........................................................................................................................
Scheduled Tasks Wizard 2 ........................................................................................................................
Scheduled Tasks Wizard 3 ........................................................................................................................
Atoll Tutorial...............................................................................................................................................
Scheduled Tasks .......................................................................................................................................
Adding Macros in Atoll ...............................................................................................................................
Atoll Object Model......................................................................................................................................

AT260_DRG_E0

23
23
24
25
26
26
27
28
67
68
69
69
70
71
72
74
74
74
75
75
77
79

xv

Developer Reference Guide

xvi

AT260_DRG_E0

Forsk 2007

Chapter 1
Introduction
This chapter gives a basic introduction to the Developer Reference Guide and the Atoll Development Toolkit.

Developer Reference Guide

18

AT260_DRG_E0

Forsk 2007

Chapter 1: Introduction

Introduction

1.1

Getting Started
Welcome to Atoll Development Toolkit. The Development Toolkit is a set of programmable extensions enabling users to
enhance the already rich functionalities found in Atoll. We recommend that you:

1.2

Read the Prerequisites to know about the development environment supported by this product.
Read the paragraph Supported extensions to learn what you can do with the development toolkit.

Follow the Tutorials1 step by step before starting your own development.

Prerequisites
The Atoll Development Toolkit is based on a set of COM interfaces allowing communication between Atoll and external
modules. This document assumes that the reader is already familiar with the basic concepts of COM. It would, however,
be quite useful to have Microsoft Online Help available.
Although COM is basically programming language independent and supported by all development environments, some
enhanced support is available for Visual C++ .NET and ActiveX Template Library (ATL) users. If you are not familiar with
this environment, especially with the very specific programming style of ATL, we recommend you to go through the ATL
tutorial provided with Visual C++ .NET.
To have the Atoll object wizard correctly installed inside Visual C++ .NET, you must install (or reinstall) Atoll after Visual
C++ .NET. Furthermore, if you consider developing a parameterised model, you must be familiar with some additional
COM concepts, such as:

Error handling interfaces

Property pages interfaces
Object persistence
Connectable objects and property change notifications

If you plan to write scripts or macros, you must be familiar with Visual Basic Scripting language.

1.3

Supported Extensions
There are currently five extension types available:

1.3.1

Propagation Models
Add-ins
Macros
Scripts
Automatic Frequency Planning Models

Propagation Models
Atoll delegates propagation calculations to external dynamic libraries registered on the computer. The software incorporates its predefined set of external models. By developing their own external propagation models, users can:

Truly customize the calculation to their own needs,

Reuse pre-existing (third-party) developments, libraries, etc.
Preserve their specific know-how.

Propagation Models can be built using any COM-compliant C++ development environment. For simplicity and clarity, this
document provides examples using Microsoft Visual C++ only.
For further information, please refer to chapter 2 "Propagation API".

1.3.2

Add-ins
To facilitate extensions in Atoll by external developers, Forsk has introduced a technology greatly inspired from the Microsoft COM automation and add-in technology.
Add-ins allow advanced users to add specific tasks that can interact with the user during their Atoll session. Add-ins can
be built using any COM-compliant C++ development environment. For simplicity and clarity, this document provides examples using Microsoft Visual C++ only.
To learn more about Add-ins, please refer to chapter 3 "General API".
1.
Currently, (Jan 2006) the wizard tutorials are only supported in Visual C++ .NET 2003 environment. The
screenshots in this document only refer to Visual C++ .NET. If Visual C++ 6.0 is installed prior to Atoll, quite similar wizard
dialogs are also available in Visual C++ 6.0. If you require assistance specifically regarding Visual C++ 6.0, please contact
the Forsk Support Team.

Forsk 2007

AT260_DRG_E0

19

Developer Reference Guide

1.3.3

Macros
Macros allow the automation of tasks in Atoll without requiring special C++ programming skills. Its possible for a macro
to interact with the user, though in a limited way. Macros are written using VBScript.
To learn more about Macros, please refer to chapter 3 "General API".

1.3.4

Scripts
Scripts allow the automation of tasks when no interaction with the user is needed. Scripts are specially useful for scheduling tasks in batch mode. Scripts are written using VBScript.
To learn more about Scripts, please refer to chapter 3 "General API".

1.3.5

Automatic Frequency Planning Models

Automatic Frequency Planning is a very important issue, which is addressed by this type of models. The highly abstract
approach used enables the developers to plan frequencies as well as other radio resources while taking into account various different parameters of the network. They can also define their own quality metrics and customize the tool to their
actual operational needs.
Automatic Frequency Planning models can be built using any COM-compliant C++ development environment. For simplicity and clarity, this document provides examples using Microsoft Visual C++ only.
To learn more about Automatic Frequency Planning Models, please refer to chapter 4 "Basic AFP API".

1.3.6

Mixing Extensions
Mixing different types of extensions within the same dynamic link library (.dll) file is not safe and can lead to unpredictable
results and loss of data. Therefore, such practice is strongly discouraged.

20

AT260_DRG_E0

Forsk 2007

Chapter 2
Propagation API
This chapter describes Atolls Propagation Model API. This API has been specifically designed for working with
propagation models in Atoll.

Developer Reference Guide

22

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

Propagation API

2.1

Propagation Models in Atoll

A propagation model for Atoll is a .dll that exports the two main calculation functions, CalculateGrid and CalculatePoints.
The first is called by Atoll for surface-area-wise calculation of studies and the second for calculations on a set of points
(measurement points for example). The CalculateGrid function outputs a matrix of path loss (attenuation values expressed
in dB), while the CalculatePoints functions generates an array of path loss (attenuation values expressed in dB).
The external model can use a set of services offered by Atoll platform.

2.2

Propagation Model Tutorial

2.2.1

Step 1: Creating The Propagation Model Project

First you will create the initial ATL project using the Atoll ATL Project Template.
1. In the Microsoft Development Environment, click New: Project in the File menu
2. Select the Atoll ATL Project Wizard
3. Type UserMdl as the project name

Figure 2.1: New Project Dialog

4. Click OK and the Atoll ATL Project Wizard will open a dialog box offering several choices to configure the initial
ATL project.

Figure 2.2: Atoll ATL Project Wizard

Forsk 2007

AT260_DRG_E0

23

Developer Reference Guide

Leave the options at their default values and click Finish. A dialog box will appear listing the main files that will be created.
These files are listed below, along with a description of each file generated by the Atoll ATL Project Wizard.

File

Description

UserMdl.cpp

Contains the implementation of DllMain, DllCanUnloadNow, DllGetClassObject,

DllRegisterServer and DllUnregisterServer. Also contains the object map, which is a list of the
ATL objects in your project. This is initially blank, since you haven't created any object yet.

UserMdl.def

The standard Windows module definition file for the DLL.

UserMdl.sln

The Visual Studio Solution Object.

UserMdl.vcproj

The project settings file.

UserMdl.idl

The interface definition language file describing the interfaces specific to your objects.

UserMdl.rc

The resource file, which initially contains the version information and a string containing the
project name.

UserMdl.rgs

The Registration Script, embedded in the project resources.

Resource.h

The header file for the resource file.

UserMdlps.vcproj

The project settings that can be used to build a proxy/stub DLL. You will not need to use this.

UserMdlps.def

The module definition file for the proxy/stub DLL.

StdAfx.cpp

The file that will #include the ATL implementation files.

StdAfx.h

The file that will #include the ATL header files.

To make the UserMdl DLL useful, you have to add the propagation model object using the Visual C++ Add Class dialog
box.

2.2.2

Step 2: Adding The Propagation Model

To add the propagation model to the ATL project:
1. Right-click the UsrMdl project in the Solution Explorer
2. Select Add: Add Class from the context menu
The Add Class dialog box appears. The different object categories are listed in the tree structure on the left:

Figure 2.3: Add Class Dialog

In the Add Class dialog box, select the category of object you want to add to your current ATL project. Set this category
to Atoll on the left, then on the right select Propagation Model and click Open.
A set of property pages is displayed allowing you to configure the model you are inserted in. Enter "Model1" as the Short
Name.

The Class field shows the C++ class name created to implement the model.
.H File and .CPP File fields show the files created containing the definition of the C++ class.
CoClass is the name of the component class for this model.
Interface is the name of the interface on which your control will implement its custom methods and properties.
Type is the descriptive name the user will see in Atoll.
ProgID is the name that identifies the model in the registry.

You have now finished setting options for your model. Click Finish.

24

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

Figure 2.4: Atoll ATL Propagation Model Object Wizard

While creating your model, several code changes and additions have been made. Following files have been created:

File

Description

Model1.h

Contains most of the implementation of the C++ class CModel1.

Model1.cpp

Contains the remaining parts of CModel1.

Model1.rgs

A text file that contains the registry script used to register the model.

Following code changes have also been made by the wizard:

A statement was added to UserMdl.idl to import AtollAPI.idl, which defines the interfaces Atoll needs to communicate with the model.
The registry script Model1.rgs was added to the project resource.
The model was added to the object map.

The default model generated by the wizard implements a very simple free space algorithm. As this tutorial deals with the
interface between Atoll and the propagation model, we will not implement a more realistic algorithm.
You are now ready to build your model:
1. In the Build menu click Build UserMdl2.
2. Once your project has finished building, run Atoll and select New from the File Menu.
3. Your model should be listed in the Module tab of the Explorer.
In the next step, you will learn how to communicate error messages to Atoll.

2.2.3

Step 3: Returning Meaningful Errors

Atoll supports the standard error handling interfaces for communicating meaningful error messages. As the Support ISupportErrorInfo option is checked by default in Step 2, this feature is already enabled in your code.
Now, you can return an error code in your Calculate functions using the CComCoClass::Error function to set the error
message:

if (frequency < 30.)

return Error("This propagation model is not valid for frequencies below
30MHz", IID_IPropagationModel);
You can read the documentation of CComCoClass::Error in the ATL documentation and the chapter Error Handling
Interfaces in the Platform SDK book to get more information about this mechanism.

2.2.4

Step 4: Adding Properties

The default free space model generated by the wizard returns a path loss in the form a + b*log(f) + c*log(d). In this step
and the next one, you will see how to let the user customize the values for a, b and c.
2.
If the compiler complains about missing files AtollAPI.idl or AtollAPI.h, ensure that the installation path of these
files (normally something like C:\Program Files\Forsk\Atoll\API\include) is part of the additional includes of your project,
either in its C++ preprocessor and MIDL settings or in the global settings (Tools: Options: Projects: VC++ Directories:
Include files). An alternate solution can be to copy them in your project directory. If it complains also about FskGIS.dll, add
path C:\Program Files\Forsk\Atoll.

Forsk 2007

AT260_DRG_E0

25

Developer Reference Guide

IModel1 is the interface that contains your custom properties. The easiest way to add a property to this interface is to right
click it in the Class View tab of Visual C++ and select Add Property.

Figure 2.5: Add Property

The Add Property to Interface dialog box will appear. Enter the details about the property you want to add:
1. On the drop-down list of Property type, select DOUBLE.
2. Type "A" as the Property Name.

Figure 2.6: Add Property Wizard

3. Click Finish to add the property.
MIDL (the program that compiles IDL files) defines a Get method that retrieves the property and a Put method that sets
the property. When MIDL compiles the file, it automatically defines those two methods in the interface by prefixing with
put_ and get_ to the property name.
Along with adding the necessary lines to the IDL file, the Add Property to Interface dialog box also adds the Get and Put
function prototypes to the class definition in Model1.h and adds an empty implementation to Model1.cpp.
The property, to be set or retrieved, requires a place to be stored. Open Model1.h and add the following line at the end of
the CModel1 class definition:

double m_a;
Now you can implement the Get and Put methods. The get_A and put_A function definitions have been added to
Model1.cpp. You have to add code similar to the following:

STDMETHODIMP CModel1::get_A(double *pVal)

{
*pVal = m_a;
return S_OK;

26

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

}
STDMETHODIMP CModel1::put_A(double newVal)
{
m_a = newVal;
return S_OK;
}
Repeat these steps for B and C properties and then use these properties in the CalculateGrid method of your model:

HRESULT CalculateGrid(
/*in*/

IRadioTransmitter* tx,

/*in*/

IRadioReceiver* rx,

/*in*/

IProgressCallback* cb,

/*in*/ double resolution,

/*in*/

double affmax,

/*out*/ IGridData **pLoss);

{
double frq; tx->GetFrequency(&frq);
double a = m_a + m_b*log10(frq) - m_c;
// TODO: Add your matrix computation code here
return S_OK;
}
Add the following lines to the CModel1 constructor to initialise the properties:

CModel1::CModel1():m_a(32.4),m_b(20.),m_c(60.)
{}
You have now three parameters in your algorithm. In the next step you will add some user interface enabling a user to
modify their values.

2.2.5

Step 5: Adding a Property Page

Property pages are implemented as separate COM objects. This allows property pages to be shared if required. To add a
property page to your model you can use the Add Class dialog box. It is accessed through Project: Add Class in the main
menu.
Select Visual C++: ATL as category on the left. Select ATL Property Page on the right and click Open.

Figure 2.7: Adding a Property Page

Once again the dialog box asking you to enter the name of the new object will appear. Call the object Model1Prop and
enter that name in the Short Name edit box.

Forsk 2007

AT260_DRG_E0

27

Developer Reference Guide

Figure 2.8: ATL Property Page Wizard

Click the Strings tab to set the title of the property page. The title of the property page is the string that appears as the tab
caption for that page.
The Doc String is a description that a property frame can display the status bar or tool tip. Atoll currently does not use this
string, but it can be set for later ease in comprehension. You are not going to generate a Helpfile at the moment, so erase
the entry in the relevant text box. Click Finish and the property page object will be created.
The following three files are created:

File

Description

Model1Prop.h

Contains the C++ class CModel1Prop implementing the property page.

Model1Prop.cpp

Includes the Model1Prop.h file.

Model1Prop.rgs

The registry script that registers the property page object.

The following code changes are also made:

The new property page is added to the object entry map.

The Model1Prop class is added to the UserMdl.idl file.
The new registry script file Model1Prop.rgs is added to the project resource.
A dialog box template is added to the project resource for the property page.
The property strings you specified are added to the resource string table.

Now, add the fields you want to display on this property page. Switch to ResourceView tab of the Visual C++ Explorer,
then open the dialog IDD_MODEL1PROP. Note that it is empty except for the label "Insert your controls here". Delete this
label and add three edit boxes with IDs IDC_A, IDC_B and IDC_C using the standard method explained in the documentation of the resource editor.
Include Model1.h at the top of the Model1Prop.h file:

#include "Model1.h"

// definition of IModel1

Now, enable the CModel1Prop class to get the properties values from your model when the property page is opened. To
do this, you must implement the Activate function in CModel1Prop.h as follows:

STDMETHOD(Activate)(HWND hWndParent, LPCRECT prc, BOOL bModal)

{
double aa,bb,cc;
BOOL equal=TRUE;
for (UINT i = 0; i < m_nObjects; i++)
{
double a,b,c;
CComQIPtr<IModel1, &IID_IModel1> pModel(m_ppUnk[i]);
pModel->get_A(&a);
pModel->get_B(&b);
pModel->get_C(&c);
if (i>0 && (a!=aa || b != bb || c != cc))
{

28

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

equal =FALSE;
break;
}
else if (i==0)
{
aa=a;
bb=b;
cc=c;
}
}
HRESULT res=IPropertyPageImpl<CModel1Prop>::Activate(hWndParent, prc,
bModal);
if (equal)
{
char buffer[50];
gcvt(aa,5,buffer);
SetDlgItemText(IDC_A, buffer);
gcvt(bb,5,buffer);
SetDlgItemText(IDC_B, buffer);
gcvt(cc,5,buffer);
SetDlgItemText(IDC_C, buffer);
}
return res;
}
Similarly, enable the CModel1Prop class to set the parameters in your model when the Apply button is pressed. Change
the Apply function in CModel1Prop.h as follows:

STDMETHOD(Apply)(void)
{
ATLTRACE(_T("CModel1Prop::Apply\n"));
double a, b, c;
char buffer[50];
GetDlgItemText(IDC_A, buffer, sizeof(buffer));
a = atof(buffer);
GetDlgItemText(IDC_B, buffer, sizeof(buffer));
b = atof(buffer);
GetDlgItemText(IDC_C, buffer, sizeof(buffer));
c = atof(buffer);
for (UINT i = 0; i < m_nObjects; i++)
{
CComQIPtr<IModel1, &IID_IModel1> pModel1(m_ppUnk[i]);
pModel1->put_A(a);
pModel1->put_B(b);
pModel1->put_C(c);
}
m_bDirty = FALSE;
return S_OK;
}
A property page could have more than one client attached to it at a time. So, the Apply function loops back and calls put_X
on each client with the value retrieved from the three edit boxes. You are using the CComQIPtr class, which performs the
QueryInterface on each object to obtain the IModel1 interface from the IUnknown (stored in the m_ppUnk array).

Forsk 2007

AT260_DRG_E0

29

Developer Reference Guide

CComPtr automatically handles the reference counting. So, you do not have to call Release on the interface. You also
must set the property page's dirty flag to indicate that the Apply button should be enabled. This occurs when the user
changes the value in one of the edit boxes. Add these lines to the message map in Model1Prop.h:

BEGIN_MSG_MAP(CModel1Prop)
CHAIN_MSG_MAP(IPropertyPageImpl<CModel1Prop>)
COMMAND_HANDLER(IDC_A, EN_CHANGE, OnParamChange)
COMMAND_HANDLER(IDC_B, EN_CHANGE, OnParamChange)
COMMAND_HANDLER(IDC_C, EN_CHANGE, OnParamChange)
END_MSG_MAP()
Now, add the OnParamChange function after the Apply function:

LRESULT OnParamChange(WORD wNotify, WORD wID, HWND hWnd, BOOL& bHandled)

{
SetDirty(TRUE);
return 0;
}
OnParamChange will be called when a WM_COMMAND message is sent with the EN_CHANGE notification for one of
the edit boxes. OnParamChange then calls SetDirty and passes TRUE to indicate the property page is now dirty and the
Apply button should be enabled:
Now, add the property page to your model. Open Model1.h and add this line to the list of base classes:

public ISpecifyPropertyPages
Add also these lines to the interface map:

BEGIN_COM_MAP(CModel1)
...
COM_INTERFACE_ENTRY(ISpecifyPropertyPages)
END_COM_MAP()
Your model now displays the standard ISpecifyPropertyPages interface. Add the following lines to the CModel1 class definition.

// ISpecifyPropertypages
STDMETHOD(GetPages)(CAUUID* pPages)
{
ATLTRACE(_T("ISpecifyPropertyPages::GetPages\n"));
pPages->cElems = 1;
pPages->pElems = (GUID*) CoTaskMemAlloc(sizeof(CLSID));
pPages->pElems[0] = CLSID_Model1Prop;
return S_OK;
}
Build your model and run Atoll. Select File New. In the list of propagation models right-click your model and you
should see your properties page.
In the next step you will see how to save the parameters a, b and c in the Atoll document file.

2.2.6

Step 6: Adding Persistence

The IPersistStream interface allows Atoll to request that your model loads and saves its persistent data to a single stream.
The wizard has already derived your model from this interface and generated a default implementation. You just have to
add code to the Load and Save functions as shown below:

STDMETHOD(Load)(LPSTREAM pStrm)
{
pStrm->Read(&m_a, sizeof(m_a), NULL);
pStrm->Read(&m_b, sizeof(m_b), NULL);
pStrm->Read(&m_c, sizeof(m_c), NULL);

30

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

return S_OK;
}

STDMETHOD(Save)(LPSTREAM pStrm, BOOL fClearDirty)

{
pStrm->Write(&m_a, sizeof(m_a), NULL);
pStrm->Write(&m_b, sizeof(m_b), NULL);
pStrm->Write(&m_c, sizeof(m_c), NULL);
return S_OK;
}
Notes:

2.2.7

As these functions may be called at any time by the program, especially in order to manage multithreading
aspects, you should not add licensing control code inside it.

Step 7: Adding Notifications

With your properties page, the user can change parameters in your model. As these changes generally affect the propagation calculations, Atoll should be notified that the old calculations are now invalid and should be recalculated.
COM provides a general mechanism for this type of communication, called "Connection Points". You can learn more about
connection points by reading the article "Connection Points" in the ATL documentation.
The wizard has already generated all the code to implement this functionality. You just have to call FireOnChanged in your
put_X functions.

STDMETHODIMP CModel1::put_A(double newVal)

{
m_a = newVal;
FireOnChanged(1);
return S_OK;
}

STDMETHODIMP CModel1::put_B(double newVal)

{
m_b = newVal;
FireOnChanged(2);
return S_OK;
}

STDMETHODIMP CModel1::put_C(double newVal)

{
m_c = newVal;
FireOnChanged(3);
return S_OK;
}

2.3

Reference Guide
This section describes all the interfaces of the Propagation Model's API. They are divided in two parts:
1.
2.

Interfaces to be implemented in the propagation model.

Interfaces implemented in Atoll platform, which offer services to the model.

Notes:

Forsk 2007

No exception can be thrown between Atoll and the model. Each error must be notified by returning an
HRESULT error code.

AT260_DRG_E0

31

Developer Reference Guide

Objects created by an Atoll method are returned locked to the model. The model must release them once it
has finished using them.

References to objects, which are sent to the model, are only valid for the duration of the method's call.

2.3.1

Structures

2.3.1.1

Polarization

2.3.1.2

2.3.1.3

POLAR_NONE

No polarization or unknown polarization

POLAR_HORIZ

Horizontal polarization

POLAR_VERT

Vertical polarization

Pixel_Type
PIXEL_POINT
point grid).

Value is point-wise and is associated with the centre of a grid's mesh (corners of a 4-

PIXEL_AREA

The value is surface-area-wise and associated to a mesh of the grid.

Extraction_Mode
EXTRACT_DEFAULT

2.3.1.4

All the geographic data present in Atoll document will be used.

Geopoint and Georect Structures

GEOPOINT is the structure for a geographic position.
GEORECT is the structure for a geographic zone.
Coordinates comply with the unit system of the Atoll document projection (usually meters).
Fields of the GEOPOINT structure:
x

X abscissa of the point

Y ordinate of the point

Fields of the GEORECT structure:

west

2.3.2

West (or min) abscissa of the zone

south

South (or min) ordinate of the zone

east

East (or max) abscissa of the zone

north

North (or max) ordinate of the zone

Model Interfaces
The following table lists optional or mandatory interfaces for an object model. Some of these interfaces are not described
here because they are parts of COM.

Format

Mandatory

Implemented
by
ATL Object
Wizard

Comments

IPropagationModel

No

Surface-area-wise and vectorial calculations

IOnProfilePropagationModel

No

Display of the profile

IObjectWithSite

Yes

Yes

**

ISupportErrorInfo

No

Yes

Management of errors by the model

ISpecifyPropertyPage

No

Yes

Management of PropertyPage

IPersistStream

No

Yes

Saving model parameters in Atoll document

IConnectionPointContainer

No

Yes

Management of calculation validity

IConnectionPoint

No

Yes

Management of calculation validity

To be able to return the result of a surface-area-wise calculation, the model must implement a class derived from IGridData:

32

Interface

Mandator
y

Implemented by
ATL Object
Wizard

Comments

IGridData

Yes

Yes

Management of a georeferenced matrix

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

To manage properties pages, the model must implement a class derived from IPropertyPage:

Interface

Mandator
y

Implemented by
ATL Object
Wizard

Comments

IPropertyPage

No

Yes

Management of properties pages.

Notes:

2.3.2.1

* Model must implement at least these two interfaces: PropagationModel or IOnProfilePropagationModel.

** Access to geographic data must be possible apart from calculations. For example, a model may need
geographic data to configure its properties pages. So, a model requires access to its client. IObjectWithSite
interface manages communication between an object (here, the model) and its site (object on the Atoll side,
which is client of the model). Model's site object implements IServiceProvider interface. A model can, by
calling the function IServiceProvider: :QueryService, get objects that provide services SID_DEM (access to
DEM) and SID_CLUTTER (access to clutter) or SID_DHM (access to clutter heights). These objects
implement IRasterGeoData, IMultiGridData, and IClutterInfo (only for the clutter).

Used COM Interfaces

Atoll can make considerable use of the following standard interfaces if they are implemented by the propagation model
object:

ISupportErrorInfo: See 2.2.3 step 3 of the tutorial to learn how to use this interface to transmit detailed error messages to Atoll.
ISpecifyPropertyPages: With this interface, Atoll is able to display a specific property page, letting the end user
change some internal properties of the propagation model object. See 2.2.5 step 5 of the tutorial.
IPersistStream: By implementing this interface, you can store data inside Atoll documents. Support for this interface is automatically provided by the ATL propagation model wizard.
IConnectionPointContainer and IConnectionPoint: If your model is a connectable object with support for the
IPropertyNotifySink outgoing interface, it can notify Atoll to consider old calculation results as invalid. See 2.2.7
step 7 of the tutorial to learn how to implement this functionality.

The last three items in the list above are all aimed at the development of parameterised propagation models and should
generally be implemented together.

2.3.2.2

IPropagationModel Interface
IPropagationModel is the interface used by Atoll to execute surface-area-wise and vectorial calculations. It provides the
following two services:

Surface-area-wise calculation: Given a transmitter, IRadioTransmitter, and a receiver, IRadioReceiver, Atoll asks
the model to calculate a path loss (attenuation values in dB) matrix. It is up to the model to determine the calculation grid.
Vectorial calculation: Given a transmitter, IRadioTransmitter, a receiver, IRadioReceiver, and a list of geographic
points GEOPOINT, Atoll uses the model to generate an array of path loss (attenuation values in dB).

Methods in Vtable order:

2.3.2.2.1

IUnknown

Description

QueryInterface

Returns pointer to supported interfaces

AddRef

Increments reference count

Release

Decrements reference count

IPropagationModel

Description

CalculateGrid

Calculates the attenuation of the signal from a given transmitter to a given receiver, on each
mesh of a grid defined by the model

CalculatePoints

Calculates the attenuation of the signal from a given transmitter to a given receiver, on each
given geographic point

IPropagationModel::CalculateGrid Method
Calculates the signal attenuation between a given transmitter and a given receiver on each mesh of a defined grid.

HRESULT CalculateGrid(
[in] IRadioTransmitter* tx,
[in] IRadioReceiver* rx,
[in] IProgressCallback* cb,
[in] double resolution,
[in]

double attmax,

[out] IGridData **pLoss)

Forsk 2007

AT260_DRG_E0

33

Developer Reference Guide

Parameters
tx:

The transmitter considered.

rx:

The radio receiver taken into account.

cb:
This object allows the model to inform its client about calculation progress. In return,
the client lets the model know whether the calculation must stop or not.
resolution:

Resolution of the result matrix in meters.

attmax:

Maximum threshold of attenuation used by Atoll (derived from the Prediction Studies).

pLoss:
The attenuation matrix resulting from calculations. To be able to send back an object
with the IGridData interface, you must create a class implementing this interface. If you use the ATL Object Wizard associated with IPropagationModel interface, a class implementing the IGridData interface will be automatically generated.
The type of this matrix is VT_ARRAY|VT_R4.

Return Values
This method supports the standard Return Values E_OUTOFMEMORY, E_ABORT and E_UNEXPECTED.
E_ABORT is sent when the user interrupts the calculation. S_OK implies that the calculation has completed without errors.

Remarks
E_NOTIMPL is not a valid Return Values for this method. If you do not have any method to determine the calculation zone,
you can let the user choose a maximum distance through the properties dialog of the model.
attmax: The different studies present in the Predictions folder may define some Min Signal Level thresholds. The maximum
value of pathloss above which coverage criterion will not be satisfied corresponds to the minimum value of this Signal
Level. This maximum pathloss value is passed to the model to enable it to optimise its calculation phase. It is not mandatory to use this parameter.

2.3.2.2.2

IPropagationModel::CalculatePoints Method
Calculates the signal attenuation between a given transmitter and a given receiver on each given geographic point.

HRESULT CalculatePoints(
[in] IRadioTransmitter* tx,
[in] IRadioReceiver* rx,
[in] ULONG nPoints,
[in, size_is(nPoints)] GEOPOINTpts[],
[out, size_is(nPoints)] float loss[])
Parameters
tx:

The transmitter considered.

rx:

The radio receiver taken into account.

nPoints:

Number of points to calculate.

pts:

Array of geographic points (see 2.3.1.4 GEOPOINT).

loss:

Array of calculated attenuation values.

Return Values
This method supports the standard Return Values E_OUTOFMEMORY and E_UNEXPECTED. S_OK means that the
calculation has completed without any error.

Remarks
E_NOTIMPL is not a valid Return Values for this method.
Contrary to CalculateGrid function, no IProgressCallback parameter was initially designed to allow the model to inform
Atoll of the calculation progress and to allow Atoll to interrupt it. The calculation time was supposed to be a lot higher in
the matrix case than in the vector case. But this assumption is no longer true. Although, there is yet a simple way to workaround this missing parameter: the model itself implements IProgressCallback2 interface.

_COM_SMARTPTR_TYPEDEF(IProgressCallback2, __uuidof(IProgressCallback2));
IProgressCallback2Ptr CModel::GetProgress()
{
IObjectWithSitePtr os = this;
IProgressCallback2Ptr sp;
os->GetSite(__uuidof(sp), reinterpret_cast<void**>(&sp));

34

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

return sp;
}
HRESULT CalculatePoints(IRadioTransmitter*
nPoints, GEOPOINT pts[],float loss[])

tx,

IRadioReceiver*

rx,

ULONG

IProgressCallback2Ptr progress=GetProgress();
progress->OnProgress(

2.3.2.3

IMultiResPropagationModel Interface
IMultiResPropagationModel is the interface used by Atoll to call a model capable of calculating at different resolutions.

2.3.2.3.1

ImultiResPropagationMod
el

Description

CalculateGrids

Calculates the multiple grids corresponding to the multiple resolutions

IMultiResPropagationModel::CalculateGrids Method
Calculates the grids corresponding to the multiple resolutions. This function will only be called for transmitters with the
same model selected as Propagation model for the Main matrix and the Extended Matrix in the Propagation tab of their
Properties dialog. Obviously, this model must implement IMultiResPropagation interface for CalculateGrids to be called.
Otherwise, CalculateGrid of interface IPropagationModel will be called twice (once for each matrix).

HRESULT CalculateGrids(
[in] IRadioTransmitter* tx,
[in] IRadioReceiver* rx,
[in] IProgressCallback* cb,
[in] IMultiResolution* res,
[out] IEnumGridData **pLoss)
Parameters
tx:

The transmitter considered.

rx:

The radio receiver taken into account.

cb:
This object allows the model to inform its client about calculation progress. In return,
the client lets the model know whether the calculation must stop or not.
res:
supported by the calculation.

The multi-resolution object that indicates to the model how many resolutions are

pLoss:

The enumerator of IGridData objects containing the results computed by the model.

pVAl:

Number of resolutions supported.

Return Values
This method supports the standard Return Values E_OUTOFMEMORY, E_ABORT and E_UNEXPECTED.
E_ABORT is sent if the user interrupts the calculations. S_OK implies that the calculation has completed without errors.

2.3.2.3.2

CalculateGrids Implementation Example

The following implementation is only provided as an example.

Interface
1. Add an additional public derivation to your model class:

class ATL_NO_VTABLE CModel1:

public CComObjectRootEx<CComSingleThreadModel>,
public CComCoClass<Cmulti, &CLSID_ Model1>,
public IObjectWithSiteImpl<C Model1>,
public IDispatchImpl<I Model1, &IID_I Model1, &LIBID_MULTIRESMODELLib>,
public IPersistStream,

Forsk 2007

AT260_DRG_E0

35

Developer Reference Guide

public IOnProfilePropagationModel,
public IPropagationModel,
public ImultiResPropagationModel
2. Add an additional interface entry in your COM map:

BEGIN_COM_MAP(CModel1)
COM_INTERFACE_ENTRY(I Model1)
COM_INTERFACE_ENTRY(IDispatch)
COM_INTERFACE_ENTRY_IMPL(IObjectWithSite)
COM_INTERFACE_ENTRY(IPersistStream)
COM_INTERFACE_ENTRY(IOnProfilePropagationModel)
COM_INTERFACE_ENTRY(IPropagationModel)
COM_INTERFACE_ENTRY(IMultiResPropagationModel)
END_COM_MAP()
3. Add the declaration of the CalculateGrids function at the end of your model class:

// IMultiResPropagationModel declaration
STDMETHOD(CalculateGrids)(
/* [in] */ IRadioTransmitter* tx,
/* [in] */ IRadioReceiver* rx,
/* [in] */ IProgressCallback* cb,
/* [in] */ IMultiResolution *res,
/* [in] */ IEnumGridData **pLoss);
};
Implementation
// Utility class CSimpleVector
template <typename T> class CSimpleVector
{
T *m_values;
size_t m_allocated, m_size;
public:
CSimpleVector() {m_values = NULL;m_allocated=m_size=0;}
~CSimpleVector() {delete[] m_values;}
void reserve(size_t s)

ATLASSERT(s>0);

delete[] m_values; m_values = NULL;

m_values=new T[s];

m_allocated=s;

m_size=0;

}
size_t reserve() const

{return m_allocated;}

size_t size() const

{return m_size;}

void fill(T t)

{for (T *ptr = begin();ptr!=end();ptr++) *ptr = t;}

void resize(size_t s)
{
ATLASSERT(s >= 0);
if (s<=m_allocated) m_size = s;
else
{
delete [] m_values;
m_values = NULL;
m_values = new T[m_allocated=m_size=s];

36

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

}
}
T *begin()

{return m_values;}

const T *begin() const

{return m_values;}

T *end()

{return m_values+m_size;}

const T *end() const

{return m_values+m_size;}

T& operator[](int i)

return m_values[i];}
const T& operator[](int i) const {
return m_values[i];}
};
// Utility typedef
typedef
CComEnum<IEnumGridData,
&__uuidof(IGridData),
_CopyInterface<IGridData> > CPropagResultEnumerator;

IGridData*,

static double sradius[2],sresol[2];

STDMETHODIMP
CModel1::CalculateGrids(IRadioTransmitter*
tx,IRadioReceiver*
rx,IProgressCallback* cb,IMultiResolution *res,IEnumGridData **pLoss)
{
try
{
long nResolutions;
res->GetCount(&nResolutions);
IProgressCallback2* progress;
progress=(IProgressCallback2*)cb;
CSimpleVector<IGridData*> allResults;
allResults.resize(nResolutions);
for (int iRes=0;iRes<nResolutions;iRes++)
{
progress->SetStatusText(iRes==0 ? L"calculating main":L"calculating
extended");
res->GetResolution(iRes, &sradius[iRes], &sresol[iRes]);

IGridData* result=NULL;
HRESULT res=CalculateGrid(tx,rx,cb,sresol[iRes],0,&result);
if (res==S_OK)
allResults[iRes]=result;
else
{
delete result;
*pLoss = NULL;
return E_FAIL;
}
}
CComObject<CPropagResultEnumerator> *pRet;
CComObject<CPropagResultEnumerator>::CreateInstance(&pRet);
pRet->Init(allResults.begin(), allResults.end(), NULL, AtlFlagCopy);
*pLoss = pRet;
(*pLoss)->AddRef();

Forsk 2007

AT260_DRG_E0

37

Developer Reference Guide

}
catch(_com_error& err)
{
HRESULT res=E_ABORT;
if (err.Error()!=res)
res=AtlReportError(GetObjectCLSID(),LPOLESTR(err.Description()),__uuidof(IMultiResPropagationModel),err.Error());
return res;
}
return S_OK;
}
Explanation
The basic idea of this example is to request the computation of each of the 2 grids to the CalculateGrid function, which is
not an operational case.
It cannot work unless some modification of the calculation zone is not done in the CalculateGrid function.
The section,

GEORECT bounds;
if (tx->GetCalculationZone(&bounds) == S_FALSE)
return Error("This model needs a calculation zone", __uuidof(IPropagationModel));

can be replaced by something like:

double radius;
if (resolution==sresol[0])
radius=sradius[0];
else radius=sradius[1];
GEORECT bounds;
bounds.west=ptTRX.x-radius;bounds.east=ptTRX.x+radius;
bounds.south=ptTRX.y-radius;bounds.north=ptTRX.y+radius;

2.3.2.4

IOnProfilePropagationModel and IOnProfilePropagationModel2

Interfaces
IOnProfilePropagationModel is the interface used by Atoll to execute a prediction calculation over a profile. Given a
transmitter, IRadioTransmitter, and a receiver, IRadioReceiver, at a given point, the model must draw a profile and return
the associated attenuation value.
Methods in Vtable order

2.3.2.4.1

IUnknown

Description

QueryInterface

Returns pointer to supported interfaces

AddRef

Increments reference count

Release

Decrements reference count

IOnProfilePropagationModel

Description

CalculateProfile

Calculates the signal attenuation and draws the profile between a given
transmitter and a receiver at a given position.

IOnProfilePropagationModel::CalculateProfile Method
Calculates the signal attenuation and draws the profile between a given transmitter to a receiver at a given position.

HRESULT CalculateProfile(

38

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

[in] IRadioTransmitter *tx,

[in] IRadioReceiver *rx,
[in] GEOPOINT *pt,
[out] float *loss,
[in] HDC hDC, [in] LPCRECT prcBounds)
Parameters
tx:

The transmitter considered.

rx:

The radio receiver taken into account.

pt:

Geographic position of the radio receiver.

loss:

Calculated attenuation value.

hDC:

Graphic context in which the profile can be drawn.

prcBounds:
Pointer to a RECT structure defining the graphic context zone in which the profile
must be drawn. The rectangle dimensions are expressed in logical coordinates.

Return Values
This method supports the standard Return Values E_OUTOFMEMORY and E_UNEXPECTED. S_OK implies that the
calculation has completed without errors.

Remarks
E_NOTIMPL is not a valid Return Values for this method.
IOnProfilePropagationModel2 is the interface used by Atoll to obtain more details about a specific profile calculation.
This interface inherits from IOnProfilePropagationModel. When a model implements this interface, a new entry called
"Model Details" is automatically added to the Profile Analysis windows context menu. The only function of this interface,
ShowDetails, is called when the user clicks on this menu item.

2.3.2.4.2

IOnProfilePropagationMode
l2

Description

ShowDetails

Gives details about the calculation of a specific profile.

IOnProfilePropagationModel2::ShowDetails Method
Gives details about the calculation of a specific profile. For example, opens a text window describing the values of different
parameters along the profile.

HRESULT ShowDetails(
[in] IRadioTransmitter *tx,
[in] IRadioReceiver *rx,
[in] GEOPOINT *pt)
Parameters
tx:

The transmitter at the start-end of the profile.

rx:

The radio receiver at the other end of the profile.

pt:

Geographic position of the radio receiver.

Return Values
S_OK implies that the details generation has completed without errors.

Remarks
The model is entirely responsible for calculating the details but also of displaying it (if necessary).

2.3.2.5

ITransmitterAntennaLossesNotIncluded Interface
ITransmitterAntennaLossesNotIncluded is a utility declarative interface used to specify that the implementation of a
model does not apply the losses due to the transmitter's antenna diagram.
If a propagation model inherits from this interface, Atoll considers that it must take into account these losses itself, in a very
basic way: it determines the azimuth and elevation angles by a direct draw of the line of sight between the transmitter and
the receiver, even if there are obstacles along the non-extracted profile.
This modelling allows, in a primitive way, not to recompute all attenuation values if only the azimuth or the elevation of the
transmitter's antenna have been updated.

Forsk 2007

AT260_DRG_E0

39

Developer Reference Guide

This interface declares no specific function.

2.3.3

Atoll Interfaces
The underlying table lists the interfaces implemented by an Atoll site object that the associated model object can use.

Interface

Comments

IServiceProvider

See COM documentation

Through the site object, the model gains access to geographical data objects implementing the following interfaces:

Interface

Comments

IRasterGeoData

Access to a point-wise value or to a profile.

IMultiGridData

Access to the list of matrix geographical data IGridData.

IClutterInfo

Access to a clutter data properties.

The IMultiGridData interface gives access to an IEnumGridData object allowing the iteration on an IGridData objects list.
Three object types may be transmitted as arguments to a model calculation method:

2.3.3.1

IRadioTransmitter

Manages transmitter properties.

IRadioReceiver

Manages receiver properties.

IProgressCallback

Manages calculation progress.

IRasterGeoData Interface
IRasterGeoData is the interface implemented by Atoll that provides access to a raster geographic data to the model. To
obtain an object supporting this interface, the model must request its site object, which supports the IServiceProvider
interface. The model will be able to obtain objects supporting SID_DEM (DEM access), SID_CLUTTER (clutter access) or
SID_DHM (clutter heights) services through a call to the QueryService method of this interface. These objects support
the IRasterGeoData interface.
Notes:

In order to know its site object, the model must implement the IObjectWithSite interface. When using the
ATL Object Wizard associated with the IPropagationModel interface, the generated class will automatically
derive from IObjectWithSiteImpl that implements the IObjectWithSite interface.

Methods in Vtable order

IUnknown

Description

QueryInterface

Returns pointer to supported interfaces

AddRef

Increments reference count

Release

Decrements reference count

IRasterGeoData

2.3.3.1.1

Description

GetBoundingBox

Returns the zone containing the geographic data.

GetGridResolution

Returns the smallest resolution available on a given zone.

ExtractProfile

Extracts a value profile of data between two points.

GetValue

Returns the data value at one given point.

PrepareFastAccessData

Pre-loads data in memory to accelerate access time.

IRasterGeoData::GetBoundingBox Method
Returns the bounding zone of the geographic data.

HRESULT GetBoundingBox( [out] GEORECT *bounds)

Parameters
bounds:

Zone containing the geographic data.

Return Values
If bounds is NULL, this method returns E_POINTER,
Else it returns S_OK.

40

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

2.3.3.1.2

IRasterGeoData::GetGridResolution Method
Returns the smallest resolution available on a given zone. If the studied zone is NULL, the returned resolution will be the
smallest available for the geographic data.

HRESULT GetGridResolution(
[in] GEORECT *bounds,
[out] double *resolution)
Parameters
bounds:

Studied zone. If NULL, the zone containing the geographic data is used.

resolution:

Smallest resolution available on the studied zone.

Return Values
If resolution is NULL, this method returns E_POINTER,
Else it returns S_OK.

2.3.3.1.3

IRasterGeoData::ExtractProfile Method
Extracts a value profile of data between two points.

HRESULT ExtractProfile(
[in] GEOPOINT *from,
[in] GEOPOINT *to,
[in] DWORD flags,
[in] ULONG nPts,
[in] double *dist,
[out] VARIANT *profile)
Parameters
from:

Geographic beginning point of the profile.

to:

Geographic ending point of the profile.

flags:

Reserved for future use. Must be zero (i.e. default EXTRACTION_MODE):

EXTRACT_DEFAULT: All the geographic data present in Atoll document will be used.

nPts:

Number of points of the profile.

dist:
Array containing the distances between all the points of the profile and the beginning
point (from). These distances may be negative (point extracted below the beginning) or may excess the profile length (point
extracted beyond the ending point). If the argument is NULL, the extraction step in the profile will be regular and derived
from nPts.
profile:
VARIANT of array type (VT_ARRAY|*) containing the nPts extracted values. For DEM
and DHM the array type will be (VT_ARRAY|VT_R4) and for the clutter (VT_ARRAY| VT_I1).

Return Values
This method supports the standard Return Values E_OUTOFMEMORY.
If from, to or profile are NULL, this method returns E_POINTER.
flags should be 0. If dist is not null, E_INVALIDARG is returned. S_OK means that the calculation completed without errors.

2.3.3.1.4

IRasterGeoData::GetValue Method
Returns the data value at one given point.

HRESULT GetValueType(
[in] GEOPOINT *pt,
[in] DWORD flags,
[out] VARIANT *value)
Parameters

Forsk 2007

pt:

Geographic position at which the data is required.

flags:

Reserved for future use. Must be set to 0.

AT260_DRG_E0

41

Developer Reference Guide

value:
Value of the geographic data at pt. If pt is outside the zone containing the geographic
data, value is of VT_ERROR type.

Return Values
If either pt or value is NULL, this method returns E_POINTER,
Else it returns S_OK.

2.3.3.1.5

IRasterGeoData::PrepareFastAccessData Method
This interface loads data, relevant to one geographic zone, in memory to accelerate access times while extracting multiple
profiles. It returns the new object IRasterGeoData associated with this memorized data.

HRESULT PrepareFastAccessData(
[in] GEORECT *bounds,
[out] IRasterGeoData **ppData)
Parameters
bounds:
geographic data will be loaded.

Geographic zone for which the data is pre-loaded. If this argument is NULL, all the

ppData:

Geographic data in memory covering the bounds zone.

Return Values
If ppData is NULL, this method returns E_POINTER.
If the user interrupts the calculation, it returns E_ABORT.
If an error is thrown, it returns DISP_E_EXCEPTION,
If the preparation was successful, it returns S_OK.

Remarks
This service is provided in for optimisation and is not necessarily called by the model. The geographic data returned only
covers the required zone. All the values associated to points outside this zone are considered by the data as null values.

2.3.3.2

IMultiGridData Interface
IMultiGridData is the interface implemented by Atoll to allow access to the list of surface-area-wise geographic data of a
given type (DEM, DHM or CLUTTER). To obtain an object supporting this interface, the model must requests its site object,
which supports the IServiceProvider interface. The model will be able to obtain objects supporting SID_DEM (DEM
access), SID_DHM (DHM access) and SID_CLUTTER (clutter access) services with the IMultiGridData interface through
a call to the QueryService method of this interface.
Methods in Vtable order

2.3.3.2.1

IUnknown

Description

QueryInterface

Returns pointer to supported interfaces

AddRef

Increments reference count

Release

Decrements reference count

IMultiGridData

Description

EnumDataSet

Returns an object enabling sequential reading of a geographic data list covering a given zone.

IMultiGridData::EnumDataSet Method
Returns an object enabling sequential reading of a geographic data list intersecting a given zone.

HRESULT EnumDataSet (
[in] GEORECT* bounds,
[out] IEnumGridData **pEnum)
Parameters
bounds:
Zone for which one wants to iterate on surface-area-wise geographic data. If bounds
is NULL, pEnum relates to the whole associated geographic data.
pEnum:
bounds.

42

Object enabling iteration on the list of surface-area-wise geographic data intersecting

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

Return Values
If pEnum is NULL, this method returns E_POINTER,
Else it returns S_OK.

2.3.3.3

IClutterInfo Interface
IClutterInfo is the interface implemented by Atoll providing access to the properties of the clutter. To obtain an object
supporting this interface, the model must request its site object, which supports the IServiceProvider interface. The model
will be able to obtain objects supporting the IClutterInfo interface through a call to the QueryService method of this interface.
Methods in Vtable order

2.3.3.3.1

IUnknown

Description

QueryInterface

Returns pointer to supported interfaces

AddRef

Increments reference count

Release

Decrements reference count

IClutterInfo

Description

GetCount

Returns the number of clutter classes

GetItemProperties

Returns the characteristics of a clutter class

IClutterInfo::GetCount Method
Returns the number of clutter classes.

HRESULT GetCount ([out] ULONG *count)

Parameters
count:

Number of clutter classes managed by Atoll.

Return Values
If count is NULL, this method returns E_POINTER,
Else it returns S_OK.

2.3.3.3.2

IClutterInfo::GetItemProperties Method
Returns the characteristics of a clutter class.

HRESULT GetItemProperties(
[in]

ULONG index,

[out] BSTR *name,

[out] DWORD *code,
[out] float *height,
[out] DWORD *color);
Parameters
index:

Index of the studied item.

name:

Name of the clutter class. If name is NULL, it is ignored.

code:

Code associated with the clutter class.

height:

Mean height of this clutter class.

color:

Color associated with the clutter class. To be used like a COLORREF.

Return Values
If code or height are NULL, this method returns E_POINTER,
If index is greater than the managed number of classes, it returns E_INVALIDARG,
Else it returns S_OK.

2.3.3.4

IEnumGridData Interface
IEnumGridData is the interface implemented by Atoll that provides access to a list of IGridData. To obtain an object
supporting this interface, the model must request its site object, which supports the IServiceProvider interface. The model

Forsk 2007

AT260_DRG_E0

43

Developer Reference Guide

will be able to obtain objects supporting SID_DEM (DEM access), SID_DHM (DHM access) and SID_CLUTTER (clutter
access) services with the IMultiGridData interface through a call to the QueryService method of this interface,. To obtain
an object supporting IEnumGridData one should call IMultiGridData::EnumDataSet. The iteration on IGridData objects
is done from the least to the most visible (as displayed in Atoll window).
Methods in Vtable order

2.3.3.4.1

IUnknown

Description

QueryInterface

Returns pointer to supported interfaces

AddRef

Increments reference count

Release

Decrements reference count

IEnumGridData

Description

Next

Returns a given number of items from the list

Skip

Skips a given number of items from the list

Reset

Goes back to the beginning of the list

Clone

Creates a new iterator from the current one

IEnumGridData::Next Method
Gets the next celt items from the list. If the remaining number of elements is smaller than the requested number, only the
remaining elements are returned. The number of extracted elements is returned as pceltFetched parameter (except if the
caller sets this value to NULL).

HRESULT Next(
[in] ULONG celt,
[out] IGridData **rgelt,
[out] ULONG * pceltFetched )
Parameters
celt:

Number of elements to extract.

rgelt:

Array of least celt size.

pceltFetched:

Number of elements in rgelt. Can be NULL if celt is set to 1.

Return Values
S_OK, if the number of returned elements is celt,
Else S_FALSE.

2.3.3.4.2

IEnumGridData::Skip Method
Skips the given number of items in the iteration sequence.

HRESULT Skip(

[in] ULONG celt)

Parameters
celt:

Number of elements to skip.

Return Values
S_OK, if the skipped element number is celt,
Else S_FALSE.

2.3.3.4.3

IEnumGridData::Reset Method
Goes back to the beginning of the iteration.

HRESULT Reset()
Return Values
S_OK.

2.3.3.4.4

IEnumGridData::Clone Method
Creates a new enumerator from the copy of the current one. The caller can use this function to memorise a given state in
the enumeration sequence and later return to this state. The new enumerator supports the same interface as the original
one.

44

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

HRESULT Clone(

[out] IEnumGridData **ppenum )

Parameters
ppenum:
argument is undefined.

Pointer's address of the new enumerator. If this method fails, the final value of this

Return Values
This method supports the standard Return Values E_INVALIDARG, E_OUTOFMEMORY and E_UNEXPECTED.

2.3.3.5

IGridData Interface
IGridData is the interface implemented by Atoll to allow access to geographic data and by the model for accessing the
calculation results. This interface allows access to georeferenced surface-area-wise data. To obtain an object supporting
this interface, the model must request its site object, which supports the IServiceProvider interface. The model will be
able to obtain objects supporting the SID_DEM (DEM access), SID_DHM (DHM access) and SID_CLUTTER (clutter
access) services of IMultiGridData interface through a call to the QueryService method of this interface. The latter gives
access to the list of surface-area-wise geographic data of the requested type (DEM, DHM or CLUTTER). The enumeration
through this list is done by using the IEnumGridData interface.
Notes:

In order for the model to return an object supporting the IGridData interface, a class implementing this
interface must be present in the model. If you use the ATL Object Wizard associated with the
IPropagationModel interface, this class will be automatically generated.

Methods in Vtable order

2.3.3.5.1

IUnknown

Description

QueryInterface

Returns pointer to supported interfaces

AddRef

Increments reference count

Release

Decrements reference count

IGridData

Description

GetDimension

Returns the size of the matrix and its georeferences

GetPixelType

Returns the value's type of the matrix elements

ExtractSubGrid

Extracts a sub-matrix

IGridData::GetDimension Method
Returns the size of the grid and its georeferencing.

HRESULT GetDimension(
[out] GEOPOINT *pt,
[out] ULONG* nx, [out] ULONG* ny,
[out] double *resX, [out] double *resY)
Parameters
pt:

Geographic origin of the grid.

nx:

Number of columns in the grid.

ny:

Number of rows in the grid.

resX:

Resolution in meters on X axis.

resY:

Resolution in meters on Y axis.

Return Values
If any one among pt, nx, ny, resX and resY is NULL, this method returns E_POINTER,
Else it returns S_OK.

2.3.3.5.2

IGridData::GetPixelType Method
Returns the value's type of the matrix elements.

HRESULT GetPixelType(
[out] PIXEL_TYPE *type)

Forsk 2007

AT260_DRG_E0

45

Developer Reference Guide

Parameters
type:
Pixel_Type):

Type of the values from the matrix. Can take two different values (see 2.3.1.2
PIXEL_AREA
PIXEL_POINT

Return Values
If type is NULL, this method returns E_POINTER,
Else it returns S_OK.

2.3.3.5.3

IGridData::ExtractSubGrid Method
Extracts and returns a sub-matrix from the original data.

HRESULT ExtractSubGrid(
[in] ULONG i0,
[in] ULONG j0,
[in] ULONG nX,
[in] ULONG nY,
[out] VARIANT

*grid)

Parameters
i0,j0:

Indexes of the origin of the sub-matrix to extract.

nX:

Number of columns to extract.

nY:

Number of rows to extract.

grid:
VARIANT of type VT_ARRAY|* containing a matrix of values of the data for the
requested zone. If the requested zone is not entirely included in the matrix, grid gets the VT_ERROR type. The matrix is
written in memory row by row. The real type of the matrix is VT_ARRAY|VT_I2 for DEM and DHM, VT_ARRAY|VT_I1 for
the clutter.

Return Values
If grid is NULL, this method returns E_POINTER,
If the requested zone is not entirely included in the matrix, it returns E_INVALIDARG,
Else it returns S_OK.

2.3.3.6

IRadioTransmitter, IRadioTransmitter2 and IRadioTransmitter3 Interfaces

IRadioTransmitter is the interface implemented by Atoll that provides access to some characteristics of the calculated
transmitter to the model.
IRadioTransmitter2 is an extension of IRadioTransmitter interface to provide the transmitter record ID.
IRadioTransmitter3 is an extension of IRadioTransmitter2 that provides an antenna enumerator.
Methods in Vtable order

46

IUnknown

Description

QueryInterface

Returns pointer to supported interfaces

AddRef

Increments reference count

Release

Decrements reference count

IRadioTransmitter

Description

GetHeight

Returns the transmitter's height

GetAltitude

Returns the altitude of the transmitter's site

GetAzimut

Returns the azimuth of the antenna

GetTilt

Returns the tilt angle of the antenna

GetFrequency

Returns the operating frequency of the transmitter

GetLocation

Returns the transmitter's position

GetPolarization

Returns the antenna's polarization

GetAntennaLoss

Returns the antenna attenuation given the pair(azimuth, elevation)

GetCalculationZone

Returns the calculation zone associated with the transmitter

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

2.3.3.6.1

IRadioTransmitter::GetHeight Method
Returns the transmitter's height.

HRESULT

GetHeight( [out] double *height)

Parameters
height:

Transmitter's height value

Return Values
If height is NULL, this method returns E_POINTER,
Else it returns S_OK.

2.3.3.6.2

IRadioTransmitter::GetAltitude Method
Returns the altitude of the transmitter's site.

HRESULT

GetAltitude( [out] double *altitude)

Parameters
altitude:

Transmitter's altitude value

Return Values
If altitude is NULL, this method returns E_POINTER,
Else it returns S_OK.

2.3.3.6.3

IRadioTransmitter::GetAzimut Method
Returns the azimuth of the antenna.

HRESULT

GetAzimut( [out] double *azimuth)

Parameters
azimuth:
wise direction.

Azimuth value of the antenna. Angle in degrees measured from the North in the clock-

Return Values
If azimuth is NULL, this method returns E_POINTER,
Else it returns S_OK.

2.3.3.6.4

IRadioTransmitter::GetTilt Method
Returns the tilt angle of the antenna.

HRESULT

GetTilt( [out] double *tilt)

Parameters
tilt:
increasing downwards.

Value of the antenna's tilt angle. Angle in degrees measured from the horizontal plane

Return Values
If tilt is NULL, this method returns E_POINTER,
Else it returns S_OK.

2.3.3.6.5

IRadioTransmitter::GetFrequency Method
Returns the operating frequency of the transmitter.

HRESULT

GetFrequency( [out] double *frequency)

Parameters
frequency:

Transmitter's frequency value in megahertz (MHz).

Return Values
If frequency is NULL, this method returns E_POINTER,

Forsk 2007

AT260_DRG_E0

47

Developer Reference Guide

Else it returns S_OK.

2.3.3.6.6

IRadioTransmitter::GetLocation Method
Returns the transmitter's position.

HRESULT

GetLocation( [out] GEOPOINT *location)

Parameters
location:

Transmitter's position

Return Values
If location is NULL, this method returns E_POINTER,
Else it returns S_OK.

2.3.3.6.7

IRadioTransmitter::GetPolarization Method
Returns the antenna's polarization.

HRESULT

GetPolarization( [out] POLARIZATION *polarization)

Parameters
polarization:

Transmitter's polarization. See 2.3.1.1 POLARIZATION.

Return Values
If polarization is NULL, this method returns E_POINTER,
Else it returns S_OK.

2.3.3.6.8

IRadioTransmitter::GetAntennaLoss Method
Returns the antenna attenuation for a given (azimuth, elevation) pair. The azimuth and elevation are with respect to the
antenna orientation, i.e. the azimuth and tilt of the antenna.

HRESULT GetAntennaLoss(
[in] double azimuth,
[in] double elevation,
[out] double *loss)
Parameters
azimuth:
The difference between the angle of the path against North and the antenna's azimuth
in degrees (angles measured clockwise).
elevation:
The difference between the angle of the path from the horizontal plane and the
antenna's tilt angle in degrees (angles increasing downwards).
loss:

Attenuation value due to antenna's directivity.

Return Values
If loss is NULL, this method returns E_POINTER,
Else it returns S_OK.

2.3.3.6.9

IRadioTransmitter::GetCalculationZone Method
Returns the calculation zone associated with the transmitter.

HRESULT GetCalculationZone( [out] GEORECT *zone)

Parameters
zone:

Calculation zone

Return Values
If zone is NULL, this method returns E_POINTER.
If the calculation zone is not defined for this transmitter, S_FALSE is returned,
Else S_OK is returned.
IRadioTransmitter2 is the interface, implemented by Atoll that provides access to other characteristics of the calculated
transmitter to the model. It inherits from IRadioTransmitter.

48

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

2.3.3.6.10

IRadioTransmitter
2

Description

GetTransmitterId

Returns the transmitter's record id

GetEirp

Returns the EIRP (in dBm) of the transmitter

GetFieldValue

Returns predefined field values of the transmitter

IRadioTransmitter2::GetTransmitterId Method
Returns the transmitter's record id.

HRESULT

GetTransmitterId( [out] VARIANT* id)

Parameter
id:

Transmitter's record id value. Must be a Double (VT_R8 type).

Return Values
If id is NULL, E_POINTER,
Else S_OK.

2.3.3.6.11

IRadioTransmitter2::GetEirp Method
Returns the EIRP (in dBm) of the transmitter.

HRESULT

GetEirp( [out] double *eirp)

Parameters
eirp:

Transmitter's EIRP.

Return Values
If eirp is NULL, E_POINTER,
Else S_OK.

2.3.3.6.12

IRadioTransmitter2::GetFieldValue Method
Returns the value of predefined fields of the transmitter.

HRESULT

GetFieldValue ( [in] BSTR name, [out] VARIANT *value)

Parameters
name:

Name of the parameter taken from the predefined list (see Predefined Fields).

value:

Value of the required attribute. The format differs according to the attribute.

Return Values
If value is NULL, E_POINTER,
Else S_OK if the required parameter belongs to the list, otherwise E_FAIL.

Predefined Fields
This function is only supported for the following fields:

Forsk 2007

"TX_ID"

Name of the transmitter

Character string

"ANTENNA_NAME"

Name of the (main) transmitting antenna

Character string

"SITE_NAME"

Site name
Character string

"ANTENNA_NAME.GAIN"

Gain of the (main) transmitting antenna

Real

"__WORKING_ZONE_BOUNDING_BOX__"

Box containing the computation zone

Variant (array of 4 ints)

"ANTENNA_NAME.DIAGRAM"

Patterns (2D) of transmitting antenna

Format provided upon request.

REDT

Remote Electrical Down Tilt: global value applied to composite pattern

(temporary value) in 100ths of a degree.

AT260_DRG_E0

49

Developer Reference Guide

2.3.3.6.13

CALC_RADIUS

Private usage of the dev. Please dont use this value because the result
is undefined.

TYPE

Private usage of the dev. Please dont use this value because the result
is undefined.

CODE_SERVICE

Private usage of the dev. Please dont use this value because the result
is undefined.

IRadioTransmitter3::EnumAntennas Method
Returns an antenna enumerator.

HRESULT EnumAntennas ([in] ANTENNAFILTER filter, [out] IEnumAntennas ** ppEnum)

TypeDefs
Filter the antennas available to the enumerator.

typedef enum _ANTENNAFILTER ANTENNAFILTER

Enumerations
Filter the antennas available to the enumerator.

enum _ANTENNAFILTER { ALL_ANTENNAS =

ALL_ANTENNAS

0 }

Returns all antennas.

Parameters
filter:

Value used to filter the antennas returned by the enumerator.

ppEnum:

Address of the returned enumerator interface pointer.

Return Values
S_OK if the enumerator was returned successfully.

Examples
Example of IRadioTransmitter3::EnumAntennas is available in section 2.3.3.13.4.

2.3.3.7

IRadioReceiver Interface
IRadioReceiver is the interface implemented by Atoll that provides access to the characteristics of the receiver type to the
model to use in calculations:
Methods in Vtable order

2.3.3.7.1

IUnknown

IUnknownDescription

QueryInterface

Returns pointer to supported interfaces

AddRef

Increments reference count

Release

Decrements reference count

IRadioTransmitter

Description

GetHeight

Returns the receiver's height

IRadioReceiver::GetHeight Method
Returns the receiver's height.

HRESULT

GetHeight( [out] double *height)

Parameters
height:

Receiver's height value

Return Values
If height is NULL, this method returns E_POINTER,
Else it returns S_OK.

50

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

2.3.3.8

IProgressCallback, IProgressCallback2 and IProgressCallback3

Interfaces
IProgressCallback is the interface implemented by Atoll enabling the model to return the calculation progress. In return,
Atoll tells the model if the calculation must be interrupted.
IProgressCallback2 enriches IProgressCallback by allowing a local user to display a status text in the Event Viewer of
Atoll.
IProgressCallback3 enriches IProgressCallback2 by allowing to display different kinds of messages in the Event Viewer
of Atoll, even in distributed mode.

2.3.3.8.1

IProgressCallback

Description

OnProgress

Updates the calculation progress

IProgressCallback::OnProgress Method
Called to let the client know the progress of a task.

HRESULT OnProgress(
[in]

DWORD

progressCurrent,

[in]

DWORD

progressMaximum)

Parameters
progressCurrent:

Amount of work already done.

progressMaximum:
of work associated to the task.

Total amount of work associated with the task. Allows the caller to refine the amount

Return Values
If the task must be interrupted, S_FALSE,
Else S_OK.
IProgressCallback2 is the interface implemented by Atoll enabling the model to display messages in the events observer
during the calculation. This interface inherits from IProgressCallback.

2.3.3.8.2

IProgressCallback
2

Description

SetStatusText

Displays a message in the events observer.

IProgressCallback2::SetStatusText Method
Called to display a message in the Event Viewer.

HRESULT SetStatusText(
[in]

LPCWSTR

szStatusText)

Parameters
szStatusText:

Message to display

Return Values
S_OK.

2.3.3.8.3

IProgressCallback3::LogEvent Method
Called to display messages of different types in the the Event Viewer.

HRESULT LogEvent([in]PROGRESS_EVENT_TYPE evtType, [in] LPCWSTR szStatusText);

Parameters
evtType:

Type of event. Belongs to the enum:

typedef enum _PROGRESS_EVENT_TYPE

{
PROGRESS_EVENT_ERR= 0,
PROGRESS_EVENT_WARN= 1,
PROGRESS_EVENT_INFO= 2

Forsk 2007

AT260_DRG_E0

51

Developer Reference Guide

} PROGRESS_EVENT_TYPE;
szStatusText:

Message to display

Return Values
S_OK.
E_FAIL, if an error occurs while trying to display a message.

2.3.3.9

IMultiResolution Interface
IMultiResolution is the interface implemented by Atoll allowing the model to know about the multi-resolution feature
supported by a calculation.

IMultiResolution

2.3.3.9.1

Description

GetCount

Number of supported resolutions

GetResolution

Gives the characteristics of a given resolution

IMultiResolution::GetCount Method
Gets the number of resolutions supported by a calculation.

HRESULT GetCount( [out]

long *pVal )

Parameters
pVAl:

Number of resolutions supported.

Return Values
If pVAl is NULL, E_POINTER,
Else S_OK.

Remarks
There are currently only two possibilities implemented:
pVal = 1 (mono-resolution) or
pVal = 2 (bi-resolution)

2.3.3.9.2

IMultiResolution::GetResolution Method
Gets the characteristics of the resolutions supported by a calculation.

HRESULT GetResolution(
[in]

long

index,

[out]

double

*radius,

[out]

double

*resolution)

Parameters
index:

Index of the resolution whose characteristics are required.

radius:

Calculation radius associated to the resolution.

resolution:

Value of the resolution.

Return Values
If either radius or resolution is NULL, E_POINTER.
If index<0 or index>1, E_INVALIDARG.
Else S_OK.

2.3.3.10

IMeasurements Method
IMeasurements is the interface implemented by Atoll enabling the model to get the measurements items (paths) of the
environment.

IMeasurements

52

Description

GetName

Gets the name of the measurements item.

GetTransmitter

Gets the transmitter to which the measurements item is attached.

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

GetReceptionHeight

2.3.3.10.1

Gets the reception height value.

GetCount

Gets the number of measurement points in the path.

GetLocations

Gets the coordinates of the measurement points of the path.

GetMeasurements

Gets the measurement values of the measurement points of the path.

IMeasurements::GetName Method
Gets the name of the measurements item.

HRESULT GetName( [out]

BSTR *bstr )

Parameters
bstr:

Name of the measurement path.

Return Values
S_OK.

2.3.3.10.2

IMeasurements::GetTransmitter Method
Gets the transmitter to which the measurement path is related.

HRESULT GetTransmitter( [out]

IRadioTransmitter **tx )

Parameters
tx:

Transmitter attached to the measurement path.

Return Values
S_OK.

2.3.3.10.3

IMeasurements::GetReceptionHeight Method
Gets the value of the reception height corresponding to the measurement path. This value is displayed under Receiver
Height in the General tab of the Properties dialog of the measurement path.

HRESULT GetReceptionHeight( [out]

double

*height )

Parameters
height:

Value of the reception height.

Return Values
S_OK.

2.3.3.10.4

IMeasurements::GetCount Method
Gets the number of points of the measurement path.

HRESULT GetCount( [out]

ULONG

*count )

Parameters
count:

Number of points in the path.

Return Values
S_OK.

2.3.3.10.5

IMeasurements::GetLocations Method
Gets the geographical positions of the points of the measurement path.

HRESULT GetLocations(
[in]

ULONG

start,

[in]

ULONG

count,

[out, size_is(count)]
[out]

Forsk 2007

ULONG

GEOPOINT

*locations,

*pceltFetched)

AT260_DRG_E0

53

Developer Reference Guide

Parameters
start:

Index of the first point to get in the path.

count:

Number of points, starting from start, to extract from the path.

locations:

Locations of the points of the measurement path

pceltFetched:
Number of points actually returned by the function. This parameter takes into account
the cases where points are (accidentally) requested past the end of the path.
For example, if there are 500 points and 300 points are requested starting at index 250, this parameter will be set to 250
(500 250).

Return Values
S_OK.

2.3.3.10.6

IMeasurements::GetMeasurements Method
Gets the measurement values for the points in the measurement path, expressed in dBm.

HRESULT GetLocations(
[in]

ULONG

start,

[in]

ULONG

count,

[out, size_is(count)]
[out]

ULONG

double

*measurements,

*pceltFetched)

Parameters
start:

Index of the first point to get in the path.

count:

Number of points, starting from start, to extract from the path.

measurements:

Measurement values for the points in the measurement path

pceltFetched:
Number of points actually returned by the function. This parameter takes into account
the cases where points are (accidentally) requested past the end of the path.
For example, if there are 500 points and 300 are requested starting at index 250, this parameter will be set to 250 (500
250).

Return Values
S_OK.

2.3.3.11

IEnumMeasurements Interface
IEnumMeasurements is the interface implemented by Atoll that provides access to a list of IMeasurements.

2.3.3.11.1

IEnumMeasurement
s

Description

Next

Returns a given number of items from the list

Skip

Skips a given number of items from the list

Reset

Goes back to the beginning of the list

Clone

Creates a new iterator from the current one

IEnumMeasurements::Next Method
Gets the next celt measurements items from the list. If the remaining number of elements is smaller than the requested
number, only the remaining elements are returned. The actual number of extracted elements is returned as pceltFetched
parameter (except if the caller sets this value to NULL).

HRESULT Next(
[in] ULONG celt,
[out] IMeasurements **rgelt,
[out] ULONG * pceltFetched )
Parameters

54

celt:

Number of elements to extract.

rgelt:

Array of least celt size.

pceltFetched:

Number of elements in rgelt. Can be NULL if celt is set to 1.

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

Return Values
E_POINTER if rgelt is NULL or celt>1 and pceltFetched is NULL.
S_OK if the number of returned elements is celt,
Else S_FALSE.

2.3.3.11.2

IEnumMeasurements::Skip Method
Skips the given number of items in the iteration sequence.

HRESULT Skip( [in] ULONG celt)

Parameters
celt:

Number of elements to skip.

Return Values
S_FALSE if the jump ends past the end of the iteration,
Else S_OK.

2.3.3.11.3

IEnumMeasurements::Reset Method
Goes back to the beginning of the iteration.

HRESULT Reset()
Return Values
S_OK.

2.3.3.11.4

IEnumMeasurements::Clone Method
Creates a new enumerator from copy of the current one. The caller can use this function to memorise a given state in the
enumeration sequence and return later to this state. The new enumerator supports the same interface as the original one.

HRESULT Clone( [out] IEnumMeasurements **ppenum )

Parameters
ppenum:
argument is undefined.

Pointer's address of the new enumerator. If this method fails, the final value of this

Return Values
E_POINTER, if ppenum is NULL.
This method supports the standard Return Values E_INVALIDARG, E_OUTOFMEMORY and E_UNEXPECTED.

2.3.3.12

IMeasurementsCatalog Interface
IMeasurementsCatalog is the interface implemented by Atoll that provides access to an IEnumMeasurements enumerator. To obtain an object supporting this interface, the model must request its site object, which supports the IServiceProvider interface for the specific SID: SID_MEASURE.

2.3.3.12.1

IMeasurementsCatalo
g

Description

EnumMeasurements

Gives access to an object supporting the IEnumMeasurements interface.

IMeasurementsCatalog::EnumMeasurements Method
Gives access to an object supporting the IEnumMeasurements interface.

HRESULT EnumMeasurements(
[in] IUnknown* filter,
[out] IEnumMeasurements **ppenum)
Parameters
filter:
If set to NULL, the enumerator will allow to run through all measurement paths in the
environment. Otherwise, it will set a filter on the measurement paths to get (see Remarks).
ppenum:

Forsk 2007

Enumerator on the objects implementing IMeasurements interface.

AT260_DRG_E0

55

Developer Reference Guide

Return Values
E_POINTER, if ppenum is NULL,
Else S_OK.

Code Example
CComQIPtr<IServiceProvider, &IID_IServiceProvider> m_srv;
GetSite(IID_IServiceProvider,(void**)&m_srv);
CComPtr<IMeasurementsCatalog> measurementsCatalog;
m_srv->
QueryService(SID_MEASURE,__uuidof(IMeasurementsCatalog),(void**)&measurementsCatalog);
Remarks
Currently, the only values supported for filter parameter are:

2.3.3.12.2

NULL gets all measurement paths in the environment.

A pointer to an object implementing IRadioTransmitter2 interface: gets all measurement paths of the environment
related to this transmitter.

IEnumGridData::Skip Method
Skips the given number of items in the iteration sequence.

HRESULT Skip( [in] ULONG celt)

Parameters
celt:

Number of elements to skip.

Return Values
S_OK, if the number of skipped elements is celt,
Else S_FALSE.

2.3.3.12.3

IEnumGridData::Reset Method
Returns to the start of the iteration.

HRESULT Reset()
Return Values
S_OK.

2.3.3.12.4

IEnumGridData::Clone Method
Creates a new enumerator from copy of the current one. The caller can use this function to memorise a given state in the
enumeration sequence and return later to this state. The new enumerator supports the same interface as the original one.

HRESULT Clone(

[out] IEnumGridData **ppenum )

Parameters
ppenum:
argument is undefined.

Pointer's address of the new enumerator. If this method fails, the final value of this

Return Values
This method supports the standard Return Values E_INVALIDARG, E_OUTOFMEMORY and E_UNEXPECTED.

2.3.3.13

IAntenna Interface
IAtenna is the interface implemented by Atoll enabling the model to get antenna properties.

IAntenna

56

Description

GetFieldValue

Gets antenna properties.

GetSectionCount

Gets the count of antenna diagram sections.

GetSection

Gets an antenna diagram section interface pointer.

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

2.3.3.13.1

IAntenna::GetFieldValue Method
Gets antenna properties.

HRESULT GetFieldValue ([in] BSTR name, [out] VARIANT * pValue)

Parameters
name:

Name of the property.

pValue:

A pointer to the location where this method writes the property value.

Notes:

The following properties are available:

Field Name

Type

"AZIMUT"

VT_R4

"NAME"

VT_BSTR

"GAIN"
"TILT"

VT_R4
VT_R4

"REDT"

VT_R4

"POWER"

VT_R4

"ISMAIN"

VT_BOOL

Return Values
S_OK if the antenna property was successfully retrieved.

Example
Example of IAntenna::GetFieldValue is available in section 2.3.3.13.4.

2.3.3.13.2

IAntenna::GetSectionCount Method
Gets the count of antenna diagram sections.

HRESULT GetSectionCount ([out] ULONG * pCount)

Antenna diagrams are made of several sections for different orientation and tilt/azimuth values.

Parameters
pCount:
diagram.

A pointer to the location where this method writes the section count of the antenna

Return Values
S_OK is the section count was successfully retrieved.

Example
Example of IAntenna::GetSectionCount is available in section 2.3.3.13.4.

2.3.3.13.3

IAntenna::GetSection Method
Gets an antenna diagram section interface pointer.

HRESULT GetSection ([in] ULONG index, [out] IAntennaPatternSection ** ppSection)

Parameters
index:
count)[.

Index of the antenna diagram section. Valid indexes are in the interval [0, (section

ppSection:

A pointer to the interface pointer used to read the antenna diagram section.

Return Values
S_OK if the antenna diagram section interface pointer was successfully retrieved.

Examples
Example of IAntenna::GetSection is available in section 2.3.3.13.4.

Forsk 2007

AT260_DRG_E0

57

Developer Reference Guide

2.3.3.13.4

Example
HRESULT DumpAntennaDiagrams(IRadioTransmitter *tx)
{
USES_CONVERSION;
HRESULT hr;
IEnumAntennas *pEnumAntennas = NULL;
IRadioTransmitter3 *pRadioTransmitter3 = NULL;
IAntenna *pAntenna = NULL;
IAntennaPatternSection *pSection = NULL;
try
{
hr = tx->QueryInterface(__uuidof(IRadioTransmitter3), (void **)
&pRadioTransmitter3);
if (FAILED(hr))
throw hr;
hr = pRadioTransmitter3->EnumAntennas(ALL_ANTENNAS, &pEnumAntennas);
if (FAILED(hr))
throw hr;
int antenna = 0;
while (hr == S_OK)
{
hr = pEnumAntennas->Next(1, &pAntenna, NULL);
if (FAILED(hr))
throw hr;
if (hr == S_OK)
{
_variant_t azimut;
_variant_t name;
_variant_t gain;
_variant_t tilt;
_variant_t redt;
_variant_t power;
_variant_t ismain;
hr = pAntenna->GetFieldValue(_bstr_t(L"AZIMUT"), &azimut);
if (FAILED(hr))
throw hr;
hr = pAntenna->GetFieldValue(_bstr_t(L"NAME"), &name);
if (FAILED(hr))
throw hr;
hr = pAntenna->GetFieldValue(_bstr_t(L"GAIN"), &gain);
if (FAILED(hr))
throw hr;
hr = pAntenna->GetFieldValue(_bstr_t(L"TILT"), &tilt);
if (FAILED(hr))
throw hr;
hr = pAntenna->GetFieldValue(_bstr_t(L"REDT"), &redt);
if (FAILED(hr))
throw hr;
hr = pAntenna->GetFieldValue(_bstr_t(L"POWER"), &power);
if (FAILED(hr))

58

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

throw hr;
hr = pAntenna->GetFieldValue(_bstr_t(L"ISMAIN"), &ismain);
if (FAILED(hr))
throw hr;
_variant_t id;
hr = pRadioTransmitter3->GetTransmitterId(&id);
if (FAILED(hr))
throw hr;
CString n;
n.Format(_T("c:\\diagrams\\tx-%d-%d.txt"), (int)id.dblVal, antenna);
CAtlFile f;
f.Create(n, GENERIC_WRITE|GENERIC_READ, FILE_SHARE_READ,
CREATE_ALWAYS);
CString l;
l.Format(_T("NAME %s\r\n"), OLE2T(name.bstrVal));
f.Write(l, l.GetLength());
l.Format(_T("AZIMUT %f\r\n"), azimut.fltVal);
f.Write(l, l.GetLength());
l.Format(_T("GAIN %f\r\n"), gain.fltVal);
f.Write(l, l.GetLength());
l.Format(_T("TILT %f\r\n"), tilt.fltVal);
f.Write(l, l.GetLength());
l.Format(_T("REDT %f\r\n"), redt.fltVal);
f.Write(l, l.GetLength());
l.Format(_T("POWER %f\r\n"), power.fltVal);
f.Write(l, l.GetLength());
l.Format(_T("ISMAIN %d\r\n"), ismain.boolVal);
f.Write(l, l.GetLength());
ULONG ulSection;
hr = pAntenna->GetSectionCount(&ulSection);
if (FAILED(hr))
throw hr;
for (ULONG i = 0; i < ulSection; ++i)
{
hr = pAntenna->GetSection(i, &pSection);
if (FAILED(hr))
throw hr;
SECTION_ORIENTATION o;
double angle;
ULONG ulSize;
hr = pSection->GetOrientation(&o, &angle);
if (FAILED(hr))
throw hr;
hr = pSection->GetPatternSize(&ulSize);
if (FAILED(hr))
throw hr;
CString l;
l.Format(_T("SECTION %d ORIENTATION %d SIZE %d\r\n"), i, o, ulSize);
f.Write(l, l.GetLength());
ANTENNAPATTERNVALUE *pPattern = new ANTENNAPATTERNVALUE[ulSize];

Forsk 2007

AT260_DRG_E0

59

Developer Reference Guide

hr = pSection->GetPattern(ulSize, pPattern);
if (FAILED(hr))
throw hr;
for (ULONG k = 0; k < ulSize; ++k)
{
CString l;
l.Format(_T("%d : %lf
pPattern[k].loss);

%lf\r\n"), k, pPattern[k].angle,

f.Write(l, l.GetLength());
}
delete [] pPattern;
pSection->Release();
pSection = NULL;
}
f.Close();
antenna++;
}
if (pAntenna)
{
pAntenna->Release();
pAntenna = NULL;
}
}
}
catch (HRESULT hrT)
{
hr = hrT;
}
catch (...)
{
hr = E_UNEXPECTED;
}
if (pSection)
pSection->Release();
if (pAntenna)
pAntenna->Release();
if (pEnumAntennas)
pEnumAntennas->Release();
if (pRadioTransmitter3)
pRadioTransmitter3->Release();
return hr;
}

2.3.3.14

IAntennaPatternSection Interface
IAtennaPatternSection is the interface implemented by Atoll enabling the model to get antenna diagram sections.

60

IAntennaPatternSection

Description

GetOrientation

Gets the orientation and angle value.

GetPatternSize

Gets the count of values (angle, loss) for the section.

GetPattern

Gets the section values.

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

2.3.3.14.1

_IAntennaPatternValue Structure
Gives the loss in dBs for a given angle.
Fields of the _IAntennaPatternValue structure:
angle

Angle in degrees.

loss

Loss in dBs.

Example of _IAntennaPatternValue structure is available in section 2.3.3.13.4.

2.3.3.14.2

TypeDefs
Gives the loss in dB for a given angle:

typedef _ANTENNAPATTERNVALUE ANTENNAPATTERNVALUE

Orientation of a antenna diagram section:

typedef enum _SECTION_ORIENTATION SECTION_ORIENTATION

2.3.3.14.3

Enumerations
Orientation of a antenna diagram section:

enum _SECTION_ORIENTATION { HORIZONTAL_SECTION, VERTICAL_SECTION }

2.3.3.14.4

HORIZONTAL_SECTION

Horizontal orientation.

VERTICAL_SECTION

Vertical orientation.

IAntennaPatternSection::GetOrientation Method
Gets the orientation and angle value.

HRESULT GetOrientation ([out] SECTION_ORIENTATION * pOrientation, [out] double

* pAngle)
Parameters
pOrientation:

A pointer to the location where this method writes the section orientation.

pAngle:
the azimuth for a vertical section.

A pointer to the location where this method writes the tilt for an horizontal section or

Return Values
S_OK if the orientation and tilt/azimuth value was successfully retrieved.

Example
Example of IAntennaPatternSection::GetOrientation is available in section 2.3.3.13.4.

2.3.3.14.5

IAntennaPatternSection::GetPatternSize Method
Gets the count of values (angle, loss) for the section.

HRESULT GetPatternSize ([out] ULONG * pCount)

Parameters
pCount:

A pointer to the location where this method writes the section size.

Return Values
S_OK if the section size was successfully retrieved.

Example
Example of IAntennaPatternSection::GetPatternSize is available in section 2.3.3.13.4.

2.3.3.14.6

IAntennaPatternSection::GetPattern Method
Gets the section values.

HRESULT GetPattern ([in] ULONG count, [out, size_is(count)] ANTENNAPATTERNVALUE

* pLoss)

Forsk 2007

AT260_DRG_E0

61

Developer Reference Guide

Parameters
count:

Number of elements of the ANTENNAPATTERNVALUE array.

pLoss:
elements.

A pointer to the location where this method writes the ANTENNAPATTERNVALUE

Notes:

The client must allocate enough memory for the pLoss array to contain count elements. The size of the
pLoss array needed to get all the antenna diagram section values is retrieved with the GetPatternSize
method.

Example
Example of IAntennaPatternSection::GetPattern is available in section 2.3.3.13.4.

2.3.3.15

IEnumAntennas Interface
IEnumAntennas is the interface implemented by Atoll that provides access to a list of IAntennas, and allows to enumerate
antennas.

2.3.3.15.1

IEnumAntennas

Description

Next

Returns a given number of items from the list

Skip

Skips a given number of items from the list

Reset

Goes back to the beginning of the list

Clone

Creates a new iterator from the current one

Example
Example of IEnumAntennas is available in section 2.3.3.13.4.

2.3.3.15.2

IEnumAntennas::Next Method
Attempts to get the next celt items in the enumeration sequence, and return them through the array pointed to by ppElements.

HRESULT Next ([in] ULONG celt, [out] IAntenna ** ppElements, [out] ULONG *
pceltFetched)
Parameters
celt:

The number of elements to be returned.

ppElements:

An array of at least size celt in which the elements are to be returned.

pceltFetched:

Pointer to the number of elements returned in ppElements, or NULL.

Return Values
S_OK if the number of elements returned is celt.
S_FALSE if the number of elements returned is less than celt.
Notes:

If fewer than the requested number of elements remain in the sequence, IEnumAntennas::Next returns only
the remaining elements. The actual number of elements is returned in pCeltFetched, unless it is NULL.

Example
Example of IEnumAntennas::Next is available in section 2.3.3.13.4.

2.3.3.15.3

IEnumAntennas::Skip Method
Attempts to skip over the next celt elements in the enumeration sequence.

HRESULT Skip ([in] ULONG celt)

Parameters
celt:

The number of elements to skip.

Return Values
S_OK if the specified number of elements was skipped.
S_FALSE if the end of the sequence was reached before skipping the requested number of elements.

62

AT260_DRG_E0

Forsk 2007

Chapter 2: Propagation API

2.3.3.15.4

IEnumAntennas::Reset Method
Resets the enumeration sequence to the beginning.

HRESULT Reset ()
Return Values
S_OK if reset was successful.

2.3.3.15.5

IEnumAntennas::Clone Method
Creates a copy of the current state of enumeration.

HRESULT Clone ([out] IEnumAntennas ** ppEnum)

Parameters
ppEnum:

On return, pointer to the location of the clone enumerator.

Return Values
S_OK if the clone was successful.
Notes:

Using this function, a particular point in the enumeration sequence can be recorded, and then returned to at
a later time. The returned enumerator is of the same actual interface as the one that is being cloned.

2.3.4

Coding Rules

2.3.4.1

Serialization of All Parameters (Multithread)

The model must serialize all its own parameters. It must not save them externally in a file (.ini for example) or in the registry.
The functions used for saving/loading parameters are Save and Load from base interface IPersistStream. These should
not be used for any other purpose, for example to check licenses etc.

2.3.4.2

Global Variables (Multithread)

The model must not use global variables.

2.3.4.3

Read Access to External Files (Distributed Computing)

The model must not read external files if their full pathname can change from one machine to another in the network.

2.3.4.4

Performance (Multithread)
The model must not make excessive memory allocations, because this causes a drastic decrease in performance.
For more information:

2.3.4.5

http://www.garret.ru/~knizhnik/threadalloc/readme.html, or
http://www.codeproject.com/cpp/rtl_scaling.asp

Use of GetFieldValue Method (Multithread)

Except in the case of explicit permission, this function of IRadioTransmitter2 interface must not be used by external
models.From version 2.2.0 of Atoll, the access permission is allowed for the following fields:
"TX_ID"

Name of the transmitter

Character string

"ANTENNA_NAME"

Name of the main transmitting antenna

Character string

"SITE_NAME"

Site name
Character string

"ANTENNA_NAME.GAIN"

Gain of the main transmitting antenna

Real

"__WORKING_ZONE_BOUNDING_BOX__"

Box containing of the computation zone

Variant (array of 4 ints)

"ANTENNA_NAME.DIAGRAM"

Patterns (2D) of transmitting antenna

Format provided upon request.

From Atoll version 2.2.2, the access permission is also allowed for the following fields:

Forsk 2007

AT260_DRG_E0

63

Developer Reference Guide

2.3.4.6

"REDT"

Remote Electric DownTilt

This field may appear as a custom field in the transmitters table.

CALC_RADIUS

Private usage of the dev. Please dont use this value because the result
is undefined.

TYPE

Private usage of the dev. Please dont use this value because the result
is undefined.

CODE_SERVICE

Private usage of the dev. Please dont use this value because the result
is undefined.

Only One Thread for Calculations (Multithread)

To force Atoll to use only one thread for path loss calculations, even on a multi-processor machine, a section of Atoll.ini
must be added:

[RemoteCalculation]
NumberOfThreads=1

2.3.4.7

Log File Generation (Multithread)

Atoll does not provide a method to manage a log file during path loss calculations. The following possibilities (non exhaustive) are just given as tracks:

2.3.4.8

Only one thread use (see 2.3.4.6 Only One Thread for Calculations (Multithread)),
Display of non remaining messages in Atoll's events viewer with SetStatusText function,
Management of one specific file per calculation instance,
Management of multi-thread access by the model's developers.

Interaction with Add-Ins (Multithread)

The simultaneous use of propagation model's API and of Add-Ins API is not supported.

64

AT260_DRG_E0

Forsk 2007

Chapter 3
General API
This chapter describes Atolls General API.

Developer Reference Guide

66

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

General API
The general API enables the implementation of add-ins, macros, and scripts.

3.1

Add-ins, Macros, and Scripts

An add-in is a program that can be fully integrated in the user interface of Atoll and which can add further features to the
software. It is an in-process COM Component written in C++. A macro or a script is a sequence of VBScript statements
in a text file. Below are the main differences between a macro, a script, and an add-in.

3.2

Script

Macro

Add-in

Interpreted

Yes

Yes

No

Format

Text

Text

Binary

Can be written in
VBScript

Yes

Yes

No

Can be written in C++

No

No

Yes

Win32 API access

No

No

Yes

Atoll user session

interaction

No

Yes

Yes

Add-in Tutorial
This tutorial has been designed to help you create add-ins. It deliberately ignores some advanced features, which will
nevertheless be detailed later.

3.2.1

Step 1: Creating the Add-in Project

First you will create the initial C++ ATL project using the ATL COM AppWizard.
1. In the Microsoft Development Environment, click New: Project in the File menu
2. Choose the Visual C++ Projects: Atoll category
3. Select the Atoll ATL Project Wizard
4. Type UserAddIn as the project name.
The dialog box should look like this:

Figure 3.1: New Project Dialog

5. Click OK and the Atoll ATL Project Wizard will open a dialog box offering several choices to configure the initial
ATL project.

Forsk 2007

AT260_DRG_E0

67

Developer Reference Guide

Figure 3.2: Atoll ATL Project Wizard

6. Leave the options at their default values and click Finish. These files are listed below, along with a description of
each file generated by the Atoll ATL Project Wizard.
Notes:

Check Support MFC in the Application Settings tab if you want to use MFC in your project.

File

Description

UserAddIn.cpp

Contains the implementation of DllMain, DllCanUnloadNow, DllGetClassObject,

DllRegisterServer and DllUnregisterServer. Also contains the object map, which is a list of the
ATL objects in your project. This is initially blank, since you haven't created any object yet.

UserAddIn.def

The standard Windows module definition file for the DLL.

UserAddIn.sln

The project solution.

UserAddIn.vcproj

Contains the project settings.

UserAddIn.idl

The interface definition language file describing the interfaces specific to your objects.

UserAddIn.rc

The resource file, which initially contains the version information and a string containing the
project name.

Resource.h

The header file for the resource file

UserAddInps.vcproj

The project settings that can be used to build a proxy/stub DLL. You will not need to use this.

UserAddInps.def

The module definition file for the proxy/stub DLL.

StdAfx.cpp

The file that will #include the ATL implementation files

StdAfx.h

The file that will #include the ATL header files.

To make the UserAddIn DLL useful, you need to insert the add-in object using the Visual C++ Add Class dialog box.

3.2.2

Step 2: Inserting and Configuring the Add-in Object

To add the add-in object into the ATL project, use the Add Class dialog box. Click Project: Add Class in the main menu.
Select the category of object you want to add to your current ATL project. Set the category as Atoll on the left, then on the
right select Atoll Addin and click Open.

68

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Figure 3.3: Add Class Dialog

A set of property pages is displayed that enable you to configure the add-in you are inserting into your project.

Figure 3.4: Atoll ATL Add-in Object Wizard 1

The Class field shows the C++ class name created to implement the add-in.
The .H File and .CPP File show the files created containing the declaration and the definition of the C++ class.
The CoClass is the name of the component class for this add-in.
Interface is the name of the interface on which your control will implement its custom methods and properties.
ProgID is the name that identifies the add-in in the registry.

To catch events generated by Atoll or add a command in Atoll General User Interface (GUI), click the Add-in tab.

Forsk 2007

AT260_DRG_E0

69

Developer Reference Guide

Figure 3.5: Atoll ATL Add-in Object Wizard 2

3.2.2.1

Commands
To add your own command in Atoll, check the Provide Command box. This command will automatically be added in the
Tools menu of Atoll. If you check the Toolbar box, your command will also be present as a command button in the Atoll
toolbar.
If your add-in provides commands, the Command Name and Method Name are mandatory.

Command Name is the text that will appear in the Tools menu of Atoll.
Method Name is the method that will be called by Atoll when the user selects the item Command Name in the
Tools menu.
Status bar Text is the text displayed in the status bar when the mouse pointer points to your command.
Tooltips Text is displayed when the mouse pointer is over a button.

3.2.2.2

Events
Application Events is checked so that the add-in is informed about events occurring at the application level in order to
be able to react to them.

3.2.2.3

Connection
A connected add-in is fully operational as soon as Atoll is launched, even if there is no document opened yet. Auto
Connect indicates that the add-in must be connected when Atoll is run. This option is written in the registry whenever your
add-in is registered. It will be read by Atoll at the very beginning of each session.
If you want to change this option afterwards, modify the value of Connect in the .rgs file of your add-in (this .rgs file will be
generated at the end of the wizard) and rebuild your project. (Change ForceRemove Connect = s 0 to ForceRemove
Connect = s 1 or vice versa)
If this option is not checked, your add-in is not connected until the user selects it in the Add-ins and Macros dialog in Atoll
(Tools > Add-ins and Macros). This dialog is available whether an Atoll document is open or not. The Add-ins and Macros
dialog is also used to disconnect a connected add-in.
Notes:

Add-in connection status between two consecutive Atoll sessions is stored in the system registry from Atoll
version 2.4.0 and above.

You have now finished selecting options for your add-in. Click OK.
When an add-in is created, several code changes and additions are made. The following files are created:

File

Description

MyTool.h

Contains the interface description of the C++ class CMyTool.

MyTool.cpp

Contains the implementation of CMyTool.

MyTool.rgs

A text file that contains the registry script used to register the model.

The following code changes are also performed by the wizard:

70

A statement is added to UserAddIn.idl to import AtollAPI.idl, which defines the part of the interfaces Atoll requires
to communicate with the add-in. Your own interface IMyTool and the corresponding CoClass are also added. As
you can see, IMyTool is defined as an IDispatch interface, because your command will be sent by Atoll using the
IDispatch::Invoke method.
The registry script MyTool.rgs is added to the project resource.
AT260_DRG_E0

Forsk 2007

Chapter 3: General API

The add-in is added to the object map in UserAddIn.cpp.

The default add-in generated by the wizard implements a very simple command, which displays a message box Hello
world From Add-in when activated.
You are now ready to build your add-in:
1. On the Build menu click Build UserAddIn.dll3.
2. Once your project has finished building, run Atoll.
3. If you have selected Auto Connect, skip next steps and go to step 6.
4. Select Add-ins and macros from the Tools Menu.
5. Check MyCommand checkbox and close the dialog.
6. You should see a new button in the toolbar.
7. Click the button, a message box is opened:

Figure 3.6: Add-in Example 1

After a document has been created or opened, open the Tools menu and select MyCommand. The same message box
will be displayed.
In the next step, you will see how to modify your code in order to catch an event generated by Atoll.

3.2.3

Step 3: Catching Events

Atoll generates events when something is about to occur or has occurred at the application level. Since Application
Events had been checked in step 2, this feature is already enabled in your code.
If you read MyTool.h, you will see:

The base class IDispEventImpl for CMyTool class, implying that events are implemented using the ATL dispatch
mechanism.
A list of sink entries between the macros BEGIN_SINK_MAP and END_SINK_MAP. Each entry matches an event
defined by the Atoll COM interface _IApplicationEvents. The third parameter of the SINK_ENTRY_EX macro is
a number, which must correspond to the number defined by Atoll and must not be modified.
A list of methods whose names are the fourth arguments of the previous macros.

If you read MyTool.cpp, you will see the implementation of these methods. The default code written by the wizard returns
S_OK when an event is caught. S_OK ignores the event.
Two categories of events are thrown:
1. Just before something happens.
2. Just after something has finished.
The method name of an event that occurs before something happens starts with Will. The method name of an event that
occurs after something has finished ends with Complete.
Some of the events methods need parameters depending on their purpose. Each Will event requires an output boolean
status that the wizard sets by default to VARIANT_TRUE, which means that Atoll can carry on its processing. If an add-in
wants to interrupt Atoll from processing at this point, because of a users choice or for any other reason, you should set
this status in the method to VARIANT_FALSE.
To illustrate this tutorial, let's suppose we want to ask the user to confirm a calculation whenever requested.
Open MyTool.cpp and modify the OnWillRun function code:

HRESULT CMyTool::OnWillRun(
IDocument *pDocument,
VARIANT_BOOL all,
VARIANT_BOOL* evtStatus
)
{

3.
If the compiler complains about missing files AtollAPI.idl or AtollAPI.h, ensure that the installation path of these
files (usually C:\Program Files\Forsk\Atoll\API\include) is a part of additional includes of your project, either in its C++
preprocessor and MIDL settings or in the global settings (Tools: Options: VC++ Directories: Include files). An alternate
solution is to copy these files to your project directory. If it complains also about FskGIS.dll, add path C:\Program
Files\Forsk\Atoll.

Forsk 2007

AT260_DRG_E0

71

Developer Reference Guide

if (all == VARIANT_FALSE)
{
if (AfxMessageBox("Run is requested. Are you sure to continue ?",
MB_YESNO|MB_ICONQUESTION) == IDYES)
*evtStatus = VARIANT_TRUE;
else
*evtStatus = VARIANT_FALSE;
}
else
*evtStatus = VARIANT_TRUE;
return S_OK;
}
Note that we test the input parameter all because we know that Atoll already asks confirmation from the user when Calculate All is requested. In this case we do not need two confirmation messages.
In this example, the input parameter Document is not used, but another example could have been to read data from this
document, do some work on this data before the run starts (with or without asking confirmation from the user).
To test these changes, build your project, restart Atoll, open a document and run a calculation (F7).

Figure 3.7: Add-in Example 2

3.2.4

Step 4: Customizing Add-ins

A single add-in can manage several commands (up to 1000). The order of these commands in the Atoll GUI depends on
the way they have been added with the IApplication::AddCommand method by your addin. You have to draw another
icon (if needed) in this case to define this new command in both the .idl file and your class, and to call IApplication::AddCommand with the appropriate parameters in the IAddin::OnConnection method.
To provide your additional command with an icon using Visual C++, just open the bitmap resource
IDB_TOOLBAR_yourClass, resize the bitmap by increasing its width by 16 pixels and draw it. In the same way, draw a
new toolbar button, open the resource editor and draw it manually.
In order for your command to be taken into account, you will have to add it through the Class tab of Visual C++. Rightclick the interface class of your concrete model class (IModel if CModel for example) and choose Add Command, then
type the name of your command.
Notes:

Your ATL project can contain several add-ins. You just have to start from step 2 to insert another add-in into
your project. However, it is recommended to have only a few add-ins and several commands in each
rather than a lot of add-ins with just a few commands ineach, for the following reasons:
- Atoll cannot define more than 1000 commands (add-ins) and 1000 commands (macros).
- Having multiple add-ins in an ATL project gives less control to the developer. Each command is
independent from the other and the order in which commands appear, either in the tool menu or in the
toolbar, only depends on the rank of their associated CLSID in the registry.

3.3

Script Tutorial
Through this tutorial, you will learn to automate some simple tasks, such as archiving databases, running calculations,
and executing scripts on a scheduled time.

3.3.1

Step 1: Writing a VBScript File

Open a text editor (Notepad for instance) and type the following code:

Option Explicit
Dim var
Dim myapp

72

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Dim doc
Sub Atoll_RunComplete(arg1, arg2)
var = 1
End Sub
Set myapp = CreateObject("Atoll.Application")
WScript.ConnectObject myapp, "Atoll_"
myapp.Visible = False
Set doc = myapp.Documents.OpenFromDatabase("Provider=SQLOLEDB.1;User ID=myName;Password=myPwd;Initial Catalog=myAtollDbName;Data Source=myServer;", "")
doc.Run True
var = 0
Do While var = 0
WScript.Sleep 1000
Loop
doc.Save("C:\mydoc.atl")
WScript.DisconnectObject myapp
doc = Null
myapp.Documents.CloseAll 0
myapp.Quit 0
myapp = Null
WScript.Quit 0
You must replace all the parameters beginning with my with your own values in the above connection string. This script,
1. Starts an invisible session of Atoll
2. Opens a new document from an existing database
3. Runs all the calculations in this document
4. Waits the end of calculations
Event RunComplete implements this wait. The syntax for catching any event is to concatenate the name of the
event to the string Atoll_. As these parameters have not been used in the above example, they have been named
arg1 and arg2. Moreover, we connect and disconnect the script using the appropriate method of WScript.
5. Saves the document
6. Exits the Atoll session
Save your script file as a .vbs, like C:\Atollmacros\tutorial.vbs.

3.3.2

Step 2: Testing the Script

To test the script:
1. Open an Explorer window
2. Select the directory where you saved the script.
3. Double-click the file.
4. Check a few minutes later that C:\TEMP\mydoc.atl has been created.

3.3.3

Step 3: Scheduling the Script

Scheduling scripts requires a Windows feature, the Task Scheduler. This tutorial describes the steps for Windows 2000.
For other operating systems, where the procedure might differ slightly, refer to Windows Help.
To open Task Scheduler,
1. Click Start
2. Point to Settings
3. Click Control Panel
4. Double-click Scheduled Tasks
5. Double click Add Scheduled Task
6. Skip the first page
7. Click Browse in the second page and select cscript.exe (probably in C:\Winnt\System32)

Forsk 2007

AT260_DRG_E0

73

Developer Reference Guide

Figure 3.8: Scheduled Tasks Wizard 1

8. Change the name of the task (for instance Atoll tutorial)
9. Choose your preferred periodicity:

Figure 3.9: Scheduled Tasks Wizard 2

The following pages enable you to define more precisely when your task should run and which user starts it.
10. In the last page, check the advance properties and finish:

Figure 3.10: Scheduled Tasks Wizard 3

11. In the next dialog, add your VBScript file name in the Run field and append \\B option to specify batch mode
(which displays no alerts, no script errors and no entry dialogs).

74

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Figure 3.11: Atoll Tutorial

12. Set account information (your password) if needed.
When you close this dialog, your task will be displayed in the Scheduled Tasks window:

Figure 3.12: Scheduled Tasks

You can modify options by editing the task properties. To control the current status of a task, choose Details in the View
menu of the Scheduled Tasks window. To open the log file, select View Log in the Advanced Window. To test the new
task, click Atoll Tutorial and select Run in the popup menu.

3.3.4

Step 4: Debugging the Script

To debug the script, use the wscript //X command line option, for example, wscript tutorial.vbs //X. You will be prompted
for the debugger you want to use. Microsoft provides a specialised script debugger to debug VBScript code, which is available in the free downloads section of http://www.microsoft.com. You can set breakpoints and inspect the contents of variables using this debugger.
While debugging, you can temporarily make Atoll visible on the desktop using:

Myapp.Visible = True

3.3.5

Step 5: Error Management

It is important to check for any error that may occur during the script execution. Microsoft Visual Basic scripting language
provides On Error Resume Next along with the Err object to manage errors. Here is our sample script tutorial.vbs with
error management:

Option Explicit
Dim var
Dim myapp
Dim doc
On Error Resume Next
Sub CatchError

Forsk 2007

AT260_DRG_E0

75

Developer Reference Guide

If Err Then
myapp.LogMessage Err.Description, 1
WScript.Echo Err.Description
End If
WScript.Echo "Script failed."
myapp.LogMessage "Script failed.", 1
If IsObject(doc) Then
doc.Close 0
doc = Null
End If
If IsObject(myapp) Then
myapp.Documents.CloseAll 0
myapp.Quit 0
myapp = Null
End If
WScript.Quit -1
End Sub
Sub Atoll_RunComplete(arg1, arg2)
var = 1
End Sub
Set myapp = CreateObject("Atoll.Application")
If Err Then
WScript.Echo "Can't create 'Atoll.Application' object."
Err.Clear
Call CatchError
End If
WScript.ConnectObject myapp, "Atoll_"
myapp.Visible = False
' Set doc = myapp.Documents.OpenFromDatabase ("Provider=SQLOLEDB.1;UserID=myName;Password=myPwd;InitialCatalog=myAtollDbName;DataSource=myServer;", "")
If Err Then Call CatchError End If
doc.Run True
If Err Then Call CatchError End If
var = 0
Do While var = 0
WScript.Sleep 1000
Loop
doc.Save("C:\mydoc.atl")
If Err Then Call CatchError End If
WScript.DisconnectObject myapp
doc = Null
myapp.Documents.CloseAll 0
myapp.Quit 0
myapp = Null
WScript.Quit 0
Error checking is activated with On Error Resume Next. When an error occurs, the script continues being executed from
the next line and the Err object is set accordingly. You can check for Err.Number (or for Err, because Number is its default
property) to catch any error.

76

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

3.4

Macro Tutorial
Macros are run by Atoll upon being invoked by the user. Macros are written in VBScript, like scripts. The difference
between scripts and macros is the execution context.
When a macro is launched from Atoll, an instance of the main object Application is automatically added as a global variable of the macro code. Therefore, it must not call CreateObject or GetObject to get an Application object.
The first line of your macro can be directly:

mydoc = ActiveDocument
The global objects name is Atoll and is optional. So, the above line is equivalent to:

mydoc = Atoll.ActiveDocument
Macros can also be invoked in response to application events.
Example:

Sub Atoll_DocumentSaveComplete(doc)
LogMessage "Archive on save running ..."
Dim status
On Error resume Next
status = doc.Archive
If Err.Number <> 0 Then
LogMessage "Archive on save failed. " & Err.Description & ".", 1
Else
If status = 1 Then
LogMessage "Archive on save failed. You must resolve the conflicts manually.", 1
MsgBox "Archive on save failed. You must resolve the conflicts manually."
Else
LogMessage "Archive on save completed successfully."
End If
End If
End Sub
The above example shows a macro used to automatically archive a document once it has been saved.

3.4.1

Adding Macros in Atoll

Once your text file written, you can add it to your Atoll session as follows:
1. Open the dialog Addins and Macros from the Tools menu,

Figure 3.13: Adding Macros in Atoll

Forsk 2007

AT260_DRG_E0

77

Developer Reference Guide

2. Click the Add button and browse for your script file,
Alternatively, you can type the name of a new (empty) file in the file selection box. Atoll will initialize this new file
with minimum default information in VBScript. Atoll interprets your file and lists all public macros found in the file
in an explorer.
3. Expand the explorer entry, select a macro and click the Run button to start the macro. (You can also double-click
the macro to run it.)
You can edit a filename when selected. The default editor is executed and the code of your macros is displayed.
You may change the code, but will require refreshing the explorer in the dialog.
You can associate an icon file to a macro:
a. Select a macro in the explorer,
b. Click the Icon button and browse for a .ico file.
c. A toolbar is added in Atoll displaying this icon.
d. To run the macro, the user can now click the toolbar button.
Notes:

If you choose a file that does not exist in the Add selection file dialog, an empty macro is created:

Public Sub Main

End Sub
You may then edit your file and add any command within the sub Main, or add another sub and execute it.
Functions may be defined (but not subroutines) for macros returning values. This is the case, for example, of all OnWill
calls as the returned value (the status value) allows the user to bypass the standard behaviour.
For functions, the name of the returned value is the same as the name of the function.

Function Atoll_WillRun(doc,success)
doc.Save

//saves the document

Atoll_WillRun = False

//intercepts the run order and cancels

//it by returning false

End Function

3.4.2

Running a Macro
As mentioned above, to run a macro the user can:
1. Select a macro in the macros dialog and click Run.
2. Double click a macro in this dialog.
3. Click the corresponding button of the toolbar.
If a problem occurs during the macro execution, an error message is displayed in a dialog box with the line number indicated. The same message is also logged in the events' observer window.
Notes:

3.4.3

Macros expecting parameters will always return an error message (Error 450) when started with the Run
button, since no parameters are actually passed.

Saving a List of Macros

Once macros have been added to an Atoll session, they can be saved in a configuration file. A new option is added for
that purpose when configuration files are saved. Note that the current configuration may be saved before opening any Atoll
document. But in this case, Macros is the only available option.
Similar to all other configuration file contents, if the configuration file is named Atoll.cfg and is stored at the same location
as Atoll.exe, Atoll will always be started with a list of macros saved in this .cfg file. Macros will be available even if no Atoll
document is open.

3.5

Reference Guide
The objects architecture is described in Atoll Objects in this section. Features provided by each object are summarized
in a table (parameters are not detailed).
The part Atoll Interfaces presents the interfaces exposed by Atoll, while the outgoing interfaces (which means interfaces
implemented by Add-ins) are described in the third chapter.
Rules contracts and advice part describes rules for writing safe code.

78

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

All constants defined by Atoll are listed in Enumerations.
And lastly, Detailed description part lists all methods, explains all input and output parameters and gives additional examples.

3.5.1

Atoll Object Model

3.5.1.1

Objects

Figure 3.14: Atoll Object Model

The following table lists the automation objects provided by Atoll.

3.5.1.2

Object name

Description

Application

Top-level object. Provides an entry point for clients to retrieve and navigate through Atolls objects.

Documents

Provides a way to iterate over and select documents in Atoll.

Document

Provides a way to open, open from a database, print, modify, and save a .ATL document.
Provides access to all data.

TabularData

Provides read and write access to radio data, read access to path loss matrices.

ChildFolder

Represents items and sub-items from the Atoll Explorer window tabs.

Properties and Methods

The following paragraphs describe these object features.

A property theProperty is defined so that when used in a VBScript language, you simply write:

myValue = theObject.theProperty

(if the property can be read)

theObject.theProperty = myValue (if the property can be written)

When used in Visual C++, you would write:

HRESULT res = theObject->get_theProperty(&myValue);

res = theObject->put_theProperty(myValue);
Differences are:

Forsk 2007

The use of interface pointers,

The HRESULT returned value
The prefix 'get_' to read the property and 'put_' to set it.

AT260_DRG_E0

79

Developer Reference Guide

Notes:

You must use this C++ syntax when you import atoll.tlb with the option raw_interfaces_only, as the code
generated by the wizard. But, if you remove this option, you may even write in C++:

myValue = theObject->theProperty;
theObject->theProperty = myValue;
You should refer to MSDN documentation to learn more about importing libraries.

A method keeps the same name in any case.

theObject.RunTheMethod()
Or

HRESULT res = theObject->RunTheMethod()

It is recommended to check the result code (HRESULT) value returned by Atoll for any method using the FAILED macro
defined in the Windows header files:

HRESULT res = theObject->RunTheMethod();

if (FAILED(hr))
{
// Handle error here
}
For clarity, error handling is omitted from code samples in this document.

3.5.1.3

Global or Member Access Functions

The application is the top-level object from which subordinate objects are obtained. To get an application object in
VBScript, use one of the following:

Set app = CreateObject(Atoll.Application)

Because Atoll registers itself in the Running Objects Table when an Atoll session is running, you can use:

Set app = GetObject(, Atoll.Application)

Notes:

Using GetObject("", Atoll.Application) note the difference in the first parameter will automatically start a
new instance of Atoll if no session is already running and attach the macro to this new instance.

But any subsequent call to GetObject with the same syntax will start a new Atoll instance too, which is not
generally what is intended. GetObject(, Atoll.Application) attaches the macro to the first Atoll session
started when several sessions are running.

In an add-in, you will get an application pointer when the OnConnection method is called. See 3.5.2 Application object and
3.5.9.2.3 OnConnection method.

3.5.2

80

Application Object
Property name

Description

Application

Returns the Application

Parent

Returns the Application

ActiveDocument

Returns the active document

Documents

Returns a collection containing the open documents

Name

Returns the name of the application, Atoll

FullName

Returns the file specification for the application, including the full pathname, e.g. C:\Program
Files\Forsk\Atoll.exe.

Path

Returns the path of the application's executable file, e.g. C:\Program Files\Forsk

WindowStatus

Sets or returns an enumerated string determining the state of the main application window
(minimized, normal, )

StatusBar

Sets the text displayed in the status bar

Visible

Sets or returns whether the application is visible to the user

Version

Returns the product version

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

LogMessage

3.5.3

Displays a message in the Atoll events viewer window (Error, Warning or Info).

Method name

Description

Quit

Exits the application and closes all open documents.

SetAddinInfo

Provides Atoll with information about an add-in. (cannot be used in VBScript)

AddCommand

Adds a command defined by an add-in to Atoll. (cannot be used in VBScript)

Active

Activates the application (inactivates all other apps).

Documents Object
This collection represents all the opened documents of an Atoll session. Use this collection to create new documents or
to iterate through project files.
To get a documents collection in VBScript:

Dim allDocs
Set allDocs = app.Documents
Or, in a C++ add-in:

IDocumentsPtr pDocs;
HRESULT hr = m_spApplication->get_Documents(&pDocs);
if (FAILED(hr))
return hr;
Property name

Description

Application

Returns the Application

Parent

Returns the Application

Count

Returns the number of items in the collection

_NewEnum

A special property that returns an enumerator object implementing IEnumVARIANT

The property _NewEnum is a special hidden property (not used directly) that you can use to write in VBScript:

Dim allDocs
Dim doc
Set allDocs = app.Documents
For Each doc In allDocs
do some work with doc
...
Next
While in C++ you will write a loop using Count property and Item method. (See 3.5.8.2.1 _NewEnum Property)

3.5.4

Method name

Description

Add

Creates a new document and adds it to the collection.

CloseAll

Closes all documents in the collection.

SaveAll

Saves all documents in the collection.

Item

Returns a Document object from the collection.

Open

Opens an existing document and adds it to the collection.

OpenFromDatabase

Create a new document initialised from a database and adds it ot the collection.

Document Object
A document represents a .atl file or a database connection. It can be managed (open, save, close, ) using its properties
and methods. A document is also the main entry to manage all the data it contains.
To get or create a document in VBScript, you can either,
1. Request the active document from the application:

Set myDoc = app.ActiveDocument

2. Or use the Documents object:

Forsk 2007

AT260_DRG_E0

81

Developer Reference Guide

Set myDoc = app.Documents.Open(C:\temp\myproject.atl)

You can also add a new document to the Documents collection or open a new document from database (see 3.5.3 Documents object).
In a C++ add-in, you will write:

IDocumentPtr pDoc;
HRESULT hr = m_spApplication->get_ActiveDocument(&pDoc);
if (FAILED(hr))
return hr;
if (pDoc == NULL)
return Error("There is no active document", __uuidof(IAddin));
Property name

Description

Application

Returns the Application.

Parent

Returns the Documents collection.

FullName

Returns the file specification for the document, including the full pathname, e.g.
C:\Program Files\Forsk\Env.atl.

Name

Returns the file name of the document excluding the file path specification.

Path

Returns the path part of the document file, e.g. C:\Program Files\Forsk.

ReadOnly

Returns True if the file/document is read only, otherwise False.

Saved

Returns True or False whether the document has changed since the last save.

CoordSystemProjection

Sets or Returns the coordinate system used in projection.

CoordSystemDisplay

Sets or Returns the coordinate system used for display.

CoordSystemInternal

Returns the coordinate system used for internal storage of sites position. (See User
Manual).

TransmissionUnit

Sets or returns the current units used for transmitted powers.

ReceptionUnit

Sets or returns the current units used for received signal levels.

DistanceUnit

Sets or returns the current displayed distance unit.

Some of the following methods take required or optional arguments, which are deliberately not listed here. Refer to the
Detailed description for more information.

3.5.5

Method name

Description

Close

Closes all windows associated with the document and removes the document from the
Documents collection.

FilePrint

Prints the document. The current page setup is used.

Save

Saves changes.

Refresh

Refreshes from database.

Archive

Archives the document into the database.

Run

Starts a calculation.

SetConfig

Sets the current configuration file.

Import

Imports a geographic file.

GetRecords

Returns a TabularData object (radio data, predictions, ).

Redraw

Redraws the map in the same way as the icon Refresh in Atoll GUI.

CenterMapOn

Centre map on given coordinates.

GetRootFolder

Returns a ChildFolder which is the root of either data tab, geo tab or modules tab.

RunPathloss

Starts the calculation of pathlosses on all or filtered transmitters, taking the validity into
account or not.

GetService

Gets a service provider object, given its name.

TabularData Object
This object stands for a table of a database even if the Atoll document is not connected to a real database and the table
does not exist in the form of a Table in the database (like PREDICTIONS or ZONES).
A TabularData is defined by its structure (number of columns, name of columns) and its content (rows = records).
Column 0 and row 0 are particular:

82

Row 0 holds the field names, i.e. the table structure description.
AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Column 0 holds a unique identifier for records, called RECORD_ID. This identifier is not persistent and must not
be used between two sessions of Atoll, nor when refreshing or archiving.

Thus, in order to get a tabular data structure, you write:

Dim i
Dim colName
Dim records
Set records = myDoc.GetRecords("Transmitters", True)
For i = 0 To records.ColumnCount
colName = records.GetValue(0, i)
Next i
The first value (for i = 0) is always RECORD_ID. The second (for i = 1) is SITE_NAME in case of TRANSMITTERS
table, and so on. The last one corresponds to i = ColumnCount.
To read the calculation radius of all transmitters, you write:

Dim i
Dim radius
Dim records
Set records = myDoc.GetRecords("Transmitters", True)
For i = 1 To records.RowCount
radius

= records.GetValue(i, CALC_RADIUS)

Next i
Note that the loop does not start with i =0 because GetValue would return the string CALC_RADIUS and not a value.
If we know that column CALC_RADIUS is number 11, we could instead write:

radius

= records.GetValue(i, 11)

But it is better to let Atoll do the correspondence by itself.

The table names you can use to request GetRecords in a document are Atoll tables defined in the documents template
initially used to create your document. It depends on the type of network.
You can also get some additional tables: PREDICTIONS, ZONES. (Structure defined in the Appendix)

Predictions tabular data gives access to path loss and signal level matrices.
Zones tabular data gives access to Calculation and Focus zones.

Property name

Forsk 2007

Description

Application

Returns the Application.

Parent

Returns the Document containing these data.

ColumnCount

Returns the number of columns.

RowCount

Returns the number of rows.

Method name

Description

Edit

Indicates which record (row) is about to be updated.

AddNew

Inserts a new empty record.

Update

Validates the changes of the currently edited record.

Delete

Deletes a row from the tabular data.

GetValue

Returns the field value at a given row and column.

SetValue

Sets the value for a given column.

GetFormattedValue

Returns a field value as a string.

Find

Searches for a value in a given column. Returns the row number of the first record that
matches the value.

FindPrimaryKey

Searches for a record whose key equals to the input parameter. Returns the row
number if a record has been found.

GetPrimaryKey

Returns the key value of a record.

AT260_DRG_E0

83

Developer Reference Guide

3.5.6

ChildFolder Object
This object represents an item of the explorer. It might be a collection of sub-items. A ChildFolder is first obtained through
a root entry point from the document and is then related to a tab of the explorer.

Dim folder
Dim item
Dim doc
Dim dataRoot
Set doc = app.ActiveDocument
dataRoot = doc.GetRootFolder(atoData)
For Each folder in dataRoot
do some work with this folder, for instance:
For Each item in folder
do some work with this item
Next
Next
Most child folders can have children and can be selected, set visible or renamed.
Only studies may be exported.

3.5.7

Property name

Description

Application

Returns the Application.

Parent

Returns the Document for a root child, otherwise returns the ChildFolder parent.

Count

Returns the number of items in the collection.

_NewEnum

A special property that returns an enumerator object implementing IEnumVARIANT.

Name

Puts or Gets the name of the item.

Item

Returns the item from the collection that matches the index.

Visible

Puts or Gets the visible flag of an item (ignored if the property does not apply to this
item).

Selected

Puts or Gets the selected flag of an item (ignored if the property does not apply to this
item).

Method name

Description

Export

Exports the item in a given format and file name. (Applies only to studies)

CentreOnMap

Centres map on this item.

Redraw

Redraws this child.

CoordSystem Object
This object contains the entire definition of a coordinate system. Several coordinate systems are used within Atoll; one for
display, one for projected geographic files and one for sites coordinates. The last one can be related to the system used
for display (see Atoll User Manual). All these systems are defined within a document.
This object is not defined in Atoll library but in the Forsk library FSKGISLib. This object can convert points from one system
to another.
As the definition of a coordinate system is quite complex, it is strongly recommended to read the Technical Reference
Guide before modifying any parameter.
To get the coordinate system used for sites coordinates in Visual Basic:

Dim doc
Dim coordSys
Set doc = app.ActiveDocument
Set coordSys = doc.CoordSystemInternal
And in C++:

IDocumentPtr pDoc;
HRESULT hr = m_spApplication->get_ActiveDocument (&pDoc);

84

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

if (FAILED(hr)) return hr;

IDispCoordSystemPtr pCoordSys;
pDoc->get_CoordSystemInternal(&pCoordSys);

3.5.8

Property name

Description

Code

Returns the system code.

Name

Returns the system name.

Description

Returns the description of the system.

Ellipsoid

Returns the integer that defines the ellipsoid.

EllipsoidName

Returns the name of the ellipsoid.

Datum

Returns the integer that defines the datum.

DatumName

Returns the name of the datum.

Unit

Returns the integer that defines the geographic unit.

ProjMethod

Returns the integer that defines the projection method.

ProjParameter

Returns all the parameters used for the projection.

Method name

Description

SetDatum

Changes the datum of the system.

SetProjection

Changes the projection of the system.

ConvertCoordsTo

Converts an array of points to another system and returns the converted points.

Pick

Opens the coordinates system dialog.

Atoll Interfaces
The following table lists the interfaces implemented by Atoll.

Object name

Description

IApplication

Access to the top-level object. Provides a standard means for clients to retrieve and
navigate through Atolls objects.

IDocuments

Provides a means to iterate over and select open documents in Atoll.

IDocument

Provides a means to open, open from database, print, change, and save a .atl
document. Provides an access to all data.

IDocument2

Inherits from IDocument interface. Adds pathloss calculation capabilities and enriches
IDocument with the generic capability to support yet unspecified features.

IDocument3

Inherits from IDocument2 interface. Adds the capability to export configuration files.

IDocument4

Adds the possibility to invoke arbitrary commands.

IResultFileProvider

Service provider starting the computations of field strength received from a transmitter
and storing the results in a binary .bil file.

ITabularData

Provides a means to read and write radio data and to read calculation results matrices.

IDispCoordSystem

Provides a means to convert coordinates from one system to another, to get

information about a system.
Note: This interface is not an interface from the Atoll library but it is defined in
FSKGISLib Forsk library.

IContextMenu

Provides a means to merge a shortcut menu associated with an Atoll Explorer window
item.

IApplicationKeyRef

Provides a means to get the Forsks reference to the dongle (fixed or floating license)
corresponding to the current Atoll session.

Notes:

To access a property in VBScript, write:

Dim vis
vis = app.Visible
Or

vis = False
app.Visible = vis

To access a property in Visual C++, write:

HRESULT hr = app->get_Visible(&vis);

Forsk 2007

AT260_DRG_E0

85

Developer Reference Guide

Or

variant_t vis = false;

app->put_Visible(vis);

3.5.8.1

IApplication Interface
To get an external description of this interface, see 3.5.2 Application.
Any add-in will get an IApplication pointer when its OnConnection method is called. The add-in should keep a reference
to this interface as long as it remains connected but this reference must be released as soon as it is disconnected. For
instance, you can use a private member in your class (automatically created by the wizard):

CComPtr<IApplication> m_spApplication;
Initialize this member when Atoll calls OnConnection on your add-in:

STDMETHODIMP CMyTool::OnConnection(IApplication*
Time, long cookie, VARIANT_BOOL* bOnConnection)

pApp,

VARIANT_BOOL

bFirst-

{
HRESULT hr = S_OK;
m_spApplication = pApp;
// additional work is omitted here
//...
return hr;
}
All references to Atoll interfaces held by an Add-in must be released when Atoll calls OnDisconnection. In particular the
IApplication pointer must be released when Atoll calls OnDisconnection.

HRESULT CMyTool::OnDisconnection(VARIANT_BOOL bLastTime)

{
m_spApplication = NULL;// Calls Release on the pointed object
return S_OK;
}

Object
Application

86

Function

Property (P)
Method (M)

HRESULT Active(VARIANT_BOOL*)
HRESULT Active(VARIANT_BOOL)

HRESULT ActiveDocument(IDocument**)

HRESULT AddCommand(BSTR, BSTR, VARIANT_BOOL,

long, VARIANT_BOOL*)

HRESULT Application(IApplication**)

HRESULT Documents(IDocuments**)

HRESULT FullName(BSTR*)

HRESULT LogMessage(BSTR, AtoLogType)

HRESULT Name(BSTR* )

HRESULT Parent(IApplication**)

HRESULT Path(BSTR*)

HRESULT Quit(AtoSaveChanges, AtoSaveStatus*)

HRESULT SetAddinInfo(long, LPDISPATCH, long,

long)

HRESULT StatusBar(BSTR)

HRESULT Version(BSTR*)

HRESULT Visible(VARIANT_BOOL*)
HRESULT Visible(VARIANT_BOOL)

HRESULT WindowStatus(AtoWindowStatus*)
HRESULT WindowStatus(AtoWindowStatus)

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

3.5.8.1.1

Application Property
(This function is provided for standard conformance only and has no real interest in Add-ins context.)
Read-only property that gets the Atoll application object itself.

HRESULT Application(IApplication**)
Parameters
pVal:
Address of pointer variable that receives the application interface pointer. Upon
successful completion, *pVal contains the requested interface pointer of the object. If the object does not support the
IApplication interface, *pVal is set to NULL.

Return Values
S_OK, if the IApplication interface is supported, otherwise E_NOINTERFACE. E_POINTER, if pVal is NULL.

3.5.8.1.2

Parent Property
(This function is provided for standard conformance only and has no real interest in Add-ins context.
Read-only property that gets the object containing the calling object. In the case of the Application object, it returns the
Application itself.)

HRESULT Parent(IApplication** pVal);

Parameters
pVal:
Address of pointer variable that receives the application interface pointer. Upon
successful completion, *pVal contains the requested interface pointer of the object. If the object does not support the
IApplication interface, *pVal is set to NULL.

Return Values
S_OK, if the IApplication interface is supported, otherwise E_NOINTERFACE. E_POINTER, if pVal is NULL.

3.5.8.1.3

Active Property
Property that gets or sets whether the application is active or not.

HRESULT Active(VARIANT_BOOL *pVal);

HRESULT Active(VARIANT_BOOL newVal /*dummy : see Remarks*/);
Parameters
pVal:

Variant either set to VARIANT_TRUE or VARIANT_FALSE (a boolean in VBScript)

newVal:

VARIANT_TRUE or VARIANT_FALSE (true or false in VBScript).

Return Values
S_OK.
E_POINTER, if pVal is NULL.

Example
Dim app
Dim act
Set app = GetObject(, Atoll.Application)
act = app.Active
app.Active = true
Remarks
Just setting an application to 'not active' has no meaning, as this does not set another application to 'active'. Thus the
newVal parameter is not used and always supposed to be VARIANT_TRUE.

3.5.8.1.4

Documents Property
Read-only property that gets the documents collection object.

HRESULT Documents(IDocuments** pVal);

Forsk 2007

AT260_DRG_E0

87

Developer Reference Guide

Parameters
pVal:
Address of pointer variable that receives the documents interface pointer. Upon
successful completion, *pVal contains the requested interface pointer of the object.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

Example
VBScript:

Dim app
Dim docs
Set app = GetObject(, Atoll.Application)
Set docs = app.Documents
C++:

IDocumentsPtr pDocs;
HRESULT hr = m_spApplication->get_Documents(&pDocs) ;
if (pDocs != NULL)
{
//...
}

3.5.8.1.5

Name Property
(This function is provided for standard conformance only and has no real interest in Add-ins context.)
Read-only property that gets the application name. The application name is always Atoll.

HRESULT Name(BSTR *pVal);

Parameters
pVal:

Address of the string that receives the application name.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.1.6

FullName Property
Read-only property that gets the full path name of the executable Atoll.exe.

HRESULT FullName(BSTR *pVal);

Parameters
pVal:

Address of the string that receives the application full path.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

Remarks
The path name returned is the absolute path (for example, "C:\Program Files\Forsk\Atoll.exe).

3.5.8.1.7

Path Property
Read-only property that gets the path of the executable Atoll.exe.

HRESULT Path(BSTR *pVal);

88

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Parameters
pVal:

Address of the string that receives the application path.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

Remarks
The path returned is provided as an absolute path (for example, "C:\Program Files\Forsk).

3.5.8.1.8

ActiveDocument Property
Read-only property that gets the active document. The active document is the opened document currently under consideration.

HRESULT ActiveDocument(IDocument** pVal);

Parameters
pVal:
Address of pointer variable that receives the document interface pointer. Upon
successful completion, *pVal contains the requested interface pointer of the object.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

Example
VBScript:

Dim app
Dim doc
Set app = GetObject(, Atoll.Application)
Set doc = app.ActiveDocument
C++:

IDocumentPtr pDoc;
HRESULT hr = m_spApplication->get_ActiveDocument(&pDoc) ;
if (pDoc != NULL)
{
//...
}

3.5.8.1.9

WindowStatus Property
Property that gets or sets the window status of the application.

HRESULT WindowStatus(AtoWindowStatus *pVal);

HRESULT WindowStatus(AtoWindowStatus newVal);
Parameters
pVal:

Address of a AtoWindowStatus that receives the status value.

newVal:

Integer variable of AtoWindowStatus type.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

Example
VBScript:

Dim app

Forsk 2007

AT260_DRG_E0

89

Developer Reference Guide

Dim status
Set app = GetObject(, Atoll.Application)
status = app.WindowStatus
app.WindowStatus = 2
C++:

AtoWindowStatus status;
HRESULT hr = m_spApplication->get_WindowStatus(&status) ;
if (SUCCEEDED(hr))
{
status = atoMinimized;
hr = m_spApplication->put_WindowStatus(status) ;
//...
}

3.5.8.1.10

StatusBar Property
Write-only property specifying the text to display in the status bar of an instance of Atoll.

HRESULT StatusBar(BSTR newVal);

Parameters
newVal:

String to display.

Return Values
S_OK.

Example
VBScript:

Dim app
Set app = GetObject(, Atoll.Application)
app.StatusBar = This is my message
C++:

HRESULT hr = m_spApplication->put_StatusBar(_bstr_t(This is my message));

if (SUCCEEDED(hr))
{
//...
}

3.5.8.1.11

Visible Property
Property that gets or sets the application visible state.

HRESULT Visible(VARIANT_BOOL *pVal);

HRESULT Visible(VARIANT_BOOL newVal);
Parameters
pVal:

Address of a variant that receives the visible state.

newVal:

Variant variable of Boolean type.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

90

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Remarks
When Atoll is not visible, all dialog boxes opened during the process that require a users answer have a default returned
value. This value is the default button set for this dialog (the focused one when opening the dialog). This returned value is
used within Atoll, it is not returned to the add-in. This value is as if the user had actually chosen it.

3.5.8.1.12

Version Property
Property that gets the application version.

HRESULT Version(BSTR *pVal);

Parameters
pVal:

Address of the string that receives the version.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

Remarks
The string is formatted like in the About Atoll dialog box (for example, 2.3.1 (Build 1155)).

3.5.8.1.13

Quit Method
Method that stops the application.

HRESULT Quit(AtoSaveChanges saveChanges, AtoSaveStatus *status);

Parameters
saveChanges:
An integer that tells if a question about saving modified documents must be prompted
to the user. See 3.5.11.2 AtoSaveChanges.
status:
atoSucceeded if save was forced to atoSaveYes or atoSaveNo or if the user was
prompted and he has answered yes. AtoCanceled if the user was prompted and answered Cancel. See 3.5.11.1 AtoSaveStatus.

Return Values
S_OK.
E_POINTER, if status is NULL.

3.5.8.1.14

LogMessage Method
Method that displays a message in the Events observer window of Atoll.

HRESULT LogMessage(BSTR msg, AtoLogType logtype);

Parameters
msg:

A string containing the message to display.

logType:
An integer that tells which icon must be used depending in the substance of the
message. See 3.5.11.6 AtoLogType.

Return Values
S_OK.

3.5.8.1.15

SetAddinInfo Method
Method called by an add-in when it is connecting to Atoll. It provides Atoll with information about the add-in.

HRESULT SetAddinInfo(long hinstance, LPDISPATCH dispatch, long idr, long cookie);

Parameters
hinstance:

The HINSTANCE of the add-in dll, cast into a Long.

dispatch:
The pointer to the dispatch interface (dispinterface) implemented by the add-in object.
When a user chooses one of the add-in commands, Atoll invokes the command using this pointer to communicate with
the add-in.

Forsk 2007

AT260_DRG_E0

91

Developer Reference Guide

idr:
A Long that is the ID of the bitmap resource containing images of all toolbar buttons
that the add-in is adding. Specify -1 if the add-in does not provide toolbar buttons.
cookie:
A Long that is the cookie identifying the add-in. Atoll passes this value to the add-in
through the add-in OnConnection method.

Return Values
S_OK.

3.5.8.1.16

AddCommand Method
Method called by an add-in in order to add a command in Atoll.

HRESULT AddCommand(BSTR cmdText, BSTR mthName, VARIANT_BOOL

toolbar, long cookie, VARIANT_BOOL* added);
Parameters
cmdText:
A String that contains substrings separated by a new line character (\n, which is
"Chr(10)" in Visual Basic). The substrings are:

Name of the command

- This is the command you want to add. This string is displayed in the Tools menu of Atoll.
Status bar string
- This is the string displayed on the status bar when the command is about to be selected.
Tooltips string
- This is the string displayed in the tool tip when the user holds the mouse pointer over the toolbar button
assigned to the command.

mthName:
command.

A String that represents the method exposed by the add-in to implement the

toolbar:
A boolean that tells Atoll if this command is assigned to a button in the toolbar. If toolbar is set to VARIANT_TRUE while no resource identifier has been passed in SetAddinInfo, E_FAIL is returned.
cookie:
A Long that is the cookie identifying the add-in. Atoll passes this value to the add-in
through the add-in OnConnection method.
added:
A Boolean that tells the add-in if the command has actually been added in the Tools
menu. If this command conflicts with an existing command, added is sets to VARIANT_FALSE. To avoid conflicts with
other add-in commands, the add-in should prefix this command with its name.

Return Values
S_OK, E_FAIL.

Remarks
Once added, a command cannot be removed during an Atoll session. A command is always enabled as long as the addin is connected. If an add-in is disconnected by the user, the command in the tool menu will be disabled and the related
button is hidden. They will be enabled again when the user reconnects the add-in. If an add-in has never been connected,
its commands do not appear.

3.5.8.2

IDocuments Interface
Object
Documents

3.5.8.2.1

Function

Property (P)
Method (M)

HRESULT _NewEnum(LPUNKNOWN*)

HRESULT Add(BSTR, IDocument**)

HRESULT Application(IApplication**)

HRESULT CloseAll(AtoSaveChanges,AtoSaveStatus*)

HRESULT Count(LONG*)

HRESULT Item(VARIANT, IDocument**)

HRESULT Open(BSTR, VARIANT_BOOL, IDocument **)

HRESULT OpenFromDatabase(VARIANT, BSTR, IDocument**)

HRESULT Parent(IApplication**)

HRESULT SaveAll();

_NewEnum Property
Specific property used to enumerate the objects of a collection.

92

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

HRESULT _NewEnum(LPUNKNOWN* ppUnk);

Parameters
ppUnk:

Address of pointer variable that receives the item interface pointer.

Return Values
S_OK.

Remarks
With Visual C++, you can browse a collection to find a particular item by using the _NewEnum property or the Item method.
In VBScript, you are not required to use the _NewEnum property because it is automatically used in the implementation
of For Each ... Next.

Example
VBScript:

Dim docs
Set docs = app.Documents
For Each doc In docs
do something with doc
Next
C++:

IDocumentsPtr pDocs;
HRESULT hr = m_spApplication->get_Documents(&pDocs) ;
if (FAILED(hr)) return hr;
for (long i = 0; i < pDocs->get_Count(); ++i)
{
IDocumentPtr pDoc;
hr = pDocs->get_Item(_variant_t(i), &pDoc);
if (FAILED(hr)) return hr;
// Do something with pDoc
}

3.5.8.2.2

Count Property
Read-only property that gets the number of items in the documents collection.

HRESULT Count(LONG *pVal);

Parameters
pVal:

Address of an integer that receives the number of items.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

Example
VBScript:

Dim nDocs
nDocs = app.Documents.Count
C++:

IDocumentsPtr pDocs;
HRESULT hr = m_spApplication->get_Documents(&pDocs) ;
if (FAILED(hr)) return hr;

Forsk 2007

AT260_DRG_E0

93

Developer Reference Guide

long nDocs = 0;
hr = pDocs->get_Count(&nDocs);
if (FAILED(hr)) return hr;

3.5.8.2.3

Item Property
Read-only property that gets one item from the documents collection.

HRESULT Item(VARIANT idx, IDocument **ppDoc);

Parameters
idx:
An integer or a string identifying the returned document. If you specify a Long, the
Item method fetches the document by its zero-based index in the collection. If you specify a String, the value is compared
to the documents' titles to find the relevant document.
pVal:
Address of pointer variable that receives the document interface pointer. Upon
successful completion, *pVal contains the requested document pointer of the object. If no matching document is found,
*pVal is set to NULL.

Return Values
S_OK.
E_FAIL, if document is not found.

Remarks
The title of a document is without its full path, with the '.atl' extension4 and is case sensitive.

3.5.8.2.4

Application Property
Read-only property that gets the Atoll application object.

HRESULT Application(IApplication** pVal);

Parameters
pVal:
Address of pointer variable that receives the application interface pointer. Upon
successful completion, *pVal contains the requested interface pointer of the object. If the object does not support the
IApplication interface, *pVal is set to NULL.

Return Values
S_OK, if the IApplication interface is supported, otherwise E_NOINTERFACE. E_POINTER, if pVal is NULL.

3.5.8.2.5

Parent Property
Read-only property that gets the object containing the parent object. In the case of the Documents object, returns the Application object.

HRESULT Parent(IApplication** pVal);

Parameters
pVal:
Address of pointer variable that receives the application interface pointer. Upon
successful completion, *pVal contains the requested interface pointer of the object. If the object does not support the
IApplication interface, *pVal is set to NULL.

Return Values
S_OK, if the IApplication interface is supported, otherwise E_NOINTERFACE. E_POINTER, if pVal is NULL.

3.5.8.2.6

Open Method
Method that opens an existing document, adds it to the collection of opened documents and returns it. This method stands
for to the interactive File Open menu command.

HRESULT Open(BSTR pathname, VARIANT_BOOL readOnly, IDocument **pDoc);

4.
Depends on checkbox Hide File Extensions for known file types in the tab Tools Folder Options Display of
Windows Explorer.

94

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Parameters
pathname:

String containing the full pathname of the document to open.

readOnly:
Possible values are:

A Variant that is a Boolean specifying whether the document is read-only or not.

VARIANT_TRUE (True) Opens as read-only.

VARIANT_FALSE (False) Opens as read/write (default).

pDoc:
Address of pointer variable that receives the opened document interface pointer.
Upon successful completion, *pDoc contains the requested interface pointer of the document. If the document cannot be
opened, *pDoc is set to NULL.

Return Values
S_OK.
E_POINTER, if pDoc is NULL.

Example
VBScript:

Dim doc
Set doc = app.Documents.Open(C:\Temp\myProject.atl)
C++:

IDocumentsPtr pDocs;
HRESULT hr = m_spApplication->get_Documents(&pDocs) ;
if (FAILED(hr)) return hr;
IDocumentPtr pDoc;
pDocs->Open(C:\\Temp\\myProject.atl, VARIANT_FALSE, &pDoc);
if (FAILED(hr)) return hr;

3.5.8.2.7

Add Method
Method that creates a new document, adds it to the collection of opened documents and returns it. This method stands
for to the interactive File New menu command.

HRESULT Add(BSTR templateName, IDocument **pDoc);

Parameters
templateName:

String containing one of the valid templates name (UMTS, xxx ).

pDoc:
Address of pointer variable that receives the created document interface pointer.
Upon successful completion, *pDoc contains the requested interface pointer of the document. If the document cannot be
created, *pDoc is set to NULL.

Return Values
S_OK.
E_POINTER, if pDoc is NULL.

Example
VBScript:

Dim doc
Set doc = app.Documents.Add(UMTS)
C++:

IDocumentsPtr pDocs;
HRESULT hr = m_spApplication->get_Documents(&pDocs) ;
if (FAILED(hr)) return hr;
IDocumentPtr pDoc;
pDocs->Add(_bstr_t(UMTS), &pDoc);
if (FAILED(hr)) return hr;

Forsk 2007

AT260_DRG_E0

95

Developer Reference Guide

3.5.8.2.8

OpenFromDatabase Method
Method that creates a new document refreshing it from the database, adds it to the collection of the opened documents
and returns it. This method stands for to the interactive File Open From Database menu command.

HRESULT OpenFromDatabase(VARIANT connection, BSTR schema, IDocument **pDoc);

Parameters
connection:
A variant of type string or VT_UNKNOWN. If connection is a string, the syntax
depends on the database to which you want to connect to. If connection is of type VT_UNKNOWN, Atoll expects an
ADODB connection pointer interface (See ADOX Documentation).
schema:
definition.

Name of the database schema, in case of databases supporting muti-schema base

If the database contains site lists, it is possible to load them in quiet mode.

The schema character string may contain the schema followed by the site lists to load,
as shown the example below. The keyword <ALL> represents all site lists, which is the same as when no parameter is
entered.
If you want to disconnect the document from the database once opened, you can add
DontKeepConnection to the schema string as shown in the examples below.
pDoc:
Address of pointer variable that receives the created document interface pointer.
Upon successful completion, *pDoc contains the requested interface pointer of the document. If the document cannot be
created, *pDoc is set to NULL.

Return Values
S_OK.
E_POINTER, if pDoc is NULL.

Example
VBScript:
Simple:

Dim doc
Set doc = app.Documents.OpenFromDatabase("Provider=Microsoft.Jet.OLEDB.4.0;User ID = USERID;Data Source=C:\Temp\MyProject.mdb","")
With a Site List:

Dim doc
Set doc = app.Documents.OpenFromDatabase("Provider=Microsoft.Jet.OLEDB.4.0;User ID = USERID;Data Source=C:\Temp\MyProject.mdb", ";sitelist0")
Notes:

Do not forget the semi-colon (;) before sitelist0.

With a Site List and Automatic Disconnection from Database:

Dim doc
Set doc = app.Documents.OpenFromDatabase("Provider=Microsoft.Jet.OLEDB.4.0;User
ID
=
USERID;Data
Source=C:\Temp\MyProject.mdb",
"DontKeepConnection
;;sitelist0")
Notes:

Do not forget the two consecutive semi-colons (;;) before sitelist0.

C++:

IDocumentsPtr pDocs;
HRESULT hr = m_spApplication->get_Documents(&pDocs);
IDocumentPtr pDoc;
pDocs-> OpenFromDatabase (_variant_t("Provider=Microsoft.Jet.OLEDB.4.0;User ID
= USERID;Data Source=C:\\Temp\\MyProject.mdb"), _bstr_t(";<ALL>"), &pDoc);
C++ example with databases supporting muti-schema base definition:

96

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

IDocumentsPtr pDocs;
hr = m_spApplication->get_Documents(&pDocs);
CComPtr<IDocument> pDoc;

3.5.8.2.9

_variant_t
connexion("Provider=MSDAORA.1;User
Source=SOURCE;Password=P");

ID

USERID;Data

pDocs->
OpenFromDatabase
(connexion,
tion;USERID;sitelist0; sitelist1"), &pDoc);

_bstr_t("DontKeepConnec-

CloseAll Method
Method that closes all the documents of the collection.

HRESULT CloseAll(AtoSaveChanges saveChanges, AtoSaveStatus *status);

Parameters
saveChanges:
An integer thatls if a question about saving modified documents must be prompted to
the user. See 3.5.11.2 AtoSaveChanges.
status:
atoSucceeded if saveChanges was forced to atoSaveYes or atoSaveNo or if the user
was prompted and he answered yes. AtoCanceled if the user was prompted and he answered Cancel. See 3.5.11.1
AtoSaveStatus.

Return Values
S_OK.
E_POINTER, if status is NULL.

3.5.8.2.10

SaveAll Method
Method that saves all the documents of the collection.

HRESULT SaveAll();
Parameters
None.

Return Values
S_OK.

3.5.8.3

IDocument Interface
Notice that an IDocument is also a service provider, which means that you can get services from this interface using the
QueryService method. To get more information about IServiceProvider interface, see COM documentation.
Thus, in order to obtain services, such as geographical data, you can call the QueryService with the appropriate service
identifier (SID_DEM, SID_CLUTTER, SID_DHM, or SID_MEASURE).
The example below shows how to get a grid containing clutter values (To make it shorter, results have not tested but should
be in a real addin).

HRESULT CMyTool::OnReadGeoData()
{
// Get clutter as a MultiGridData
IDocumentPtr pDoc;
m_spApplication->get_ActiveDocument(&pDoc) ;
IServiceProviderPtr provider;
pDoc->QueryInterface(__uuidof(IServiceProvider),(void**)(&provider));
IRasterGeoDataPtr pGeoData;
provider->QueryService(SID_CLUTTER, &pGeoData);
IMultiGridDataPtr multiGrid;
// Extract an area from the first grid
GEORECT bounds;

Forsk 2007

bounds.west = 985800;

bounds.east = 987300;

bounds.south = 1879100;

bounds.north = 1880700;

AT260_DRG_E0

97

Developer Reference Guide

IEnumGridDataPtr pEnum;
multiGrid->EnumDataSet(&bounds, &pEnum);
IGridDataPtr gridData;
ULONG pclFetched = -1;
pEnum->Next(1, &gridData, &pclFetched);
GEOPOINT p0;
ULONG nx, ny;
double resX, resY;
gridData->GetDimension(&p0, &nx, &ny, &resX, &resY);
long i0 = long((bounds.west - p0.x)/resX);
long j0 = long((bounds.south - p0.y)/resY);
_variant_t vgrid;
gridData->ExtractSubGrid(i0,

j0, nx, ny, &vgrid);

// Read and display the value of the centre of the area

GEOPOINT pt;
pt.x = bounds.west + (bounds.east - bounds.west)/2;
pt.y = bounds.south + (bounds.north - bounds.south)/2;
_variant_t value;
pGeoData->GetValue(&pt, 0, &value);
value.ChangeType(VT_R4);
float floatValue = V_R4(&value);
CString msg;
msg.Format("center value = %f",

floatValue);

::MessageBox(NULL, msg, "Info", MB_OK|MB_ICONINFORMATION);

return S_OK;
}
You may also gain access to the nth Best Signal export matrices through the same mechanism:

IDocumentPtr* pDoc = activeDoc;

IServiceProviderPtr serv = pDoc;
ISignalsPtr sig;
hr = serv->QueryService(SID_SIGNALS,&sig);
Interface Isignals, which was added in Atoll 2.2.2, only supports GetSortedSignals function described further in this document.

Object
Document

98

Function

Property (P)
Method (M)

HRESULT Application(IApplication**)

HRESULT Archive(AtoArchiveStatus*)

HRESULT CenterMapOn(double*, double*)

HRESULT Close(AtoSaveChanges, AtoSaveStatus*)

HRESULT CoordSystemDisplay(IDispCoordSystem**)
HRESULT CoordSystemDisplay(IDispCoordSystem*)

HRESULT CoordSystemInternal(IDispCoordSystem**)

HRESULT CoordSystemProjection(IDispCoordSystem**)
HRESULT CoordSystemProjection(IDispCoordSystem*)

HRESULT DistanceUnit(AtoDistanceUnit*)
HRESULT DistanceUnit(AtoDistanceUnit)

HRESULT FilePrint()

HRESULT FullName(BSTR*)

HRESULT GetRecords(BSTR, VARIANT_BOOL, ITabularData**)

HRESULT GetRootFolder(AtoRootType,IChildFolder**)

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

3.5.8.3.1

HRESULT Import(BSTR)

HRESULT Name(BSTR*)

HRESULT Parent(IApplication**)

HRESULT Path(BSTR*)

HRESULT ReadOnly(VARIANT_BOOL*)

HRESULT ReceptionUnit(AtoReceptionUnit*)
HRESULT ReceptionUnit(AtoReceptionUnit)

HRESULT Redraw();

HRESULT Refresh(AtoRefreshPriority)

HRESULT Run(VARIANT_BOOL)

HRESULT Save(BSTR)

HRESULT Saved(VARIANT_BOOL*)

HRESULT SetConfig(BSTR)

HRESULT TransmissionUnit(AtoTransmissionUnit *)
HRESULT TransmissionUnit(AtoTransmissionUnit)

Application Property
Read-only property that gets the Atoll application object.

HRESULT Application(IApplication** pVal);

Parameters
pVal:
Address of pointer variable that receives the application interface pointer. Upon
successful completion, *pVal contains the requested interface pointer of the object. If the object does not support the
IApplication interface, *pVal is set to NULL.

Return Values
S_OK, if the IApplication interface is supported, otherwise E_NOINTERFACE. E_POINTER, if pVal is NULL.

3.5.8.3.2

Parent Property
Read-only property that gets the object containing the calling object. In the case of the Document object, it returns the
Documents collection.

HRESULT Parent([out, retval] IDocuments* *pVal);

Parameters
pVal:
IDocuments.

Address of pointer variable that receives the documents interface pointer. See 3.5.8.2

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.3.3

FullName Property
Read-only property that gets the documents full path name with the extension.

HRESULT FullName(BSTR *pVal);

Parameters
pVal:

Address of string that receives the documents full path name.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.3.4

Name Property
Read-only property that gets the documents name without the extension.

HRESULT Name(BSTR *pVal);

Forsk 2007

AT260_DRG_E0

99

Developer Reference Guide

Parameters
pVal:

Address of string that receives the documents name.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.3.5

Path Property
Read-only property that gets the documents path.

HRESULT Path(BSTR *pVal);

Parameters
pVal:

Address of string that receives the documents path.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

Remarks
In the case of an unsaved document (new or when opening from database), the three functions above: Name, Path and
FullName return empty strings. Nevertheless, if the user wants to know the automatic name, he must call the Item function
of IDocuments interface and pass a string, "DocumentX", where X is the number of the document, as the first variant
parameter.

3.5.8.3.6

ReadOnly Property
Read-only property that returns true or false depending on whether the document is read only or not.

HRESULT ReadOnly(VARIANT_BOOL *pVal);

Parameters
pVal:

Address of the boolean that receives the documents state.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.3.7

Saved Property
Gets a document's saved status, indicating whether a document has changed since it was last saved.

HRESULT Saved(VARIANT_BOOL *pVal);

Parameters
pVal:
Address of the boolean that receives the documents state. True indicates that the
document has not changed since it was created or last saved. False indicates that the document has been changed since
it was last saved.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.3.8

CoordSystemProjection Property
Property that gets or sets the current coordinate system used for projected geographic data (see User Manual).

HRESULT CoordSystemProjection(IDispCoordSystem** pVal);

HRESULT CoordSystemProjection(IDispCoordSystem* newVal);
Parameters
pVal:
Address of pointer variable that receives the coordinate system interface pointer (see
3.5.8.17 IDispCoordSystem interface and 3.5.7 CoordSystem object).

100

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

newVal:

Address of reference variable that contains the coordinate system interface pointer.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.3.9

CoordSystemDisplay Property
Property that gets or sets the current coordinate system used for display (see User Manual).

HRESULT CoordSystemDisplay(IDispCoordSystem** pVal);

HRESULT CoordSystemDisplay(IDispCoordSystem* newVal);
Parameters
pVal:
Address of pointer variable that receives the coordinate system interface pointer (see
3.5.8.17 IDispCoordSystem interface and 3.5.7 CoordSystem object).
newVal:

Address of reference variable that contains the coordinate system interface pointer.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.3.10

CoordSystemInternal Property
Read-only property that gets the current coordinate system used for sites coordinates.
The internal system will automatically change if the coordinate system used for display is changed and the document is
not connected to a database. If the document is connected to a database, the internal system is the one used for the first
archive in database (see User Manual).

HRESULT CoordSystemInternal(IDispCoordSystem** pVal);

Parameters
pVal:
Address of pointer variable that receives the coordinate system interface pointer (see
3.5.8.17 IDispCoordSystem interface and 3.5.7 CoordSystem object.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.3.11

TransmissionUnit Property
Property that sets or gets the current transmission power units.

HRESULT TransmissionUnit(AtoTransmissionUnit *pVal);

HRESULT TransmissionUnit(AtoTransmissionUnit newVal);
Parameters
pVal:
nit).

Address of an integer variable that receives the unit (see 3.5.11.8 AtoTransmissionU-

newVal:

Integer containing the new unit.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.3.12

ReceptionUnit Property
Property that sets or gets the current reception unit used for signal level.

HRESULT ReceptionUnit(AtoReceptionUnit *pVal);

HRESULT ReceptionUnit(AtoReceptionUnit newVal);
Parameters
pVal:

Forsk 2007

Address of an integer variable that receives the unit (see 3.5.11.9 AtoReceptionUnit).
AT260_DRG_E0

101

Developer Reference Guide

newVal:

Integer containing the new unit.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.3.13

DistanceUnit Property
Property that sets or gets the current displayed distance unit.

HRESULT DistanceUnit(AtoDistanceUnit *pVal);

HRESULT DistanceUnit(AtoDistanceUnit newVal);
Parameters
pVal:

Address of an integer variable that receives the unit (see 3.5.11.10 AtoDistanceUnit).

newVal:

Integer containing the new unit.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.3.14

Close Method
Method that closes a document. The document is removed from the Documents collection.

HRESULT Close(AtoSaveChanges, AtoSaveStatus* status);

Parameters
saveChanges:
An integer that tells if a question about saving modified documents must be prompted
to the user (see 3.5.11.2 AtoSaveChanges).
status:
atoSucceeded if save was forced to atoSaveYes or atoSaveNo or if the user was
prompted and he has answered yes. AtoCanceled if the user was prompted and he answered Cancel (see 3.5.11.1
AtoSaveStatus).

Return Values
S_OK.
E_POINTER,if status is NULL.

3.5.8.3.15

FilePrint Method
Sends a document to the current printer. The current print settings are used.

HRESULT FilePrint();
Parameters
None.

Return Values
S_OK.

3.5.8.3.16

Save Method
Saves a document. This method is equivalent to the File Save or File Save As menu commands, depending on the
input filename.

HRESULT Save(BSTR fileName);

It is possible to save a document in the form of an Atoll project file (.atl), to export it to an MS-Access database (.mdb) or
to export it to an Oracle database. The examples below show how to perform these actions.

Parameters
filename:
A string specifying the full path of the file to which you want to save the document. If
you omit the name, it uses the default name specified by the FullName property.

102

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Return Values
S_OK or E_FAIL.

Examples
Saving a document as a .atl file:

IDocumentPtr pDoc;
hr = m_spApplication->get_ActiveDocument(&pDoc);
pDoc->Save(_bstr_t(L"C:\\Temp\\MyProject.atl"));
return S_OK;
Exporting a document to an MS-Access database:

IDocumentPtr pDoc;
hr = m_spApplication->get_ActiveDocument(&pDoc);
pDoc->Save(_bstr_t((L"C:\Temp\MyProject.mdb"));
return S_OK;
Exporting a document to an Oracle database:

IDocumentPtr pDoc;
hr = m_spApplication->get_ActiveDocument(&pDoc);
pDoc->Save(_bstr_t(L"Provider=MSDAORA.1;User ID = USERID;Data Source=SOURCE;
Password=P"));
return S_OK;

3.5.8.3.17

Refresh Method
Method that refreshes the document from the database. The connection must have been previously defined.

HRESULT Refresh(AtoRefreshPriority priority);

Parameters
priority:
(see 3.5.11.3 AtoRefreshPriority).

A Long value that tells Atoll if previous changes in the project file must be kept or not

Return Values
S_OK or E_FAIL.

3.5.8.3.18

Archive Method
Method that archives the document into the database. The connection must have been previously defined.

HRESULT Archive(AtoArchiveStatus *status);

Parameters
status:

Address of an integer that will receive the status result of the operation.

Return Values
S_OK or E_FAIL.
E_POINTER, if status is NULL.

3.5.8.3.19

Run Method
Method that starts a calculation.

HRESULT Run(VARIANT_BOOL all);

Parameters
all:
Variant of type Boolean, which is VARIANT_TRUE if all previous results must be
deleted before calculation starts, or VARIANT_FALSE if only invalid matrices must be calculated. This method is the same
as the commands Calculate and Calculate All in the Tools menu.

Forsk 2007

AT260_DRG_E0

103

Developer Reference Guide

Return Values
S_OK or E_FAIL.

3.5.8.3.20

SetConfig Method
Method that loads a configuration file

HRESULT SetConfig(BSTR fileName);

Parameters
fileName:

String containing the full path name of the configuration file to load.

Return Values
S_OK or E_FAIL.

Remarks
The configuration file is an XML file. It may contain geographic configuration and folder configurations (see User Manual
.cfg files).
The configurations contained in the .cfg file will replace the corresponding configurations in the document. The previous
one in the document will be lost.
If you want to add some geographic information to a document, youd rather use the Import function instead.

3.5.8.3.21

Import Method
Method that loads a file containing geographic data.

HRESULT Import(BSTR fileName);

Parameters
fileName:

String containing the full path name of the file to load.

Return Values
S_OK or E_FAIL.

Remarks
The geographic file can be:

An XML file. All data from its geographic section are loaded (see User Manual .geo files).
Any file format supported by Atoll (.bil, .tif, etc).

The geographic content of the imported file (whatever the type: cfg, geo, bil, ) is added to the current configuration of
the geographic data in the document. It does not remove the older geographic configuration.
If you want to replace the geographic configuration of a document, youd rather use the SetConfig function instead.
Warning:

3.5.8.3.22

Because this method has no input parameter, you have to ensure that no inputs are requested from the
user when importing the file (like file type, georeferencement, ) if the application is not visible.

GetRecords Method
Method that returns a tabular data for a requested category of records.

HRESULT GetRecords(BSTR tableName, VARIANT_BOOL all,ITabularData **pRecords);

Parameters
tableName:

String containing the name of the table from which the records are requested.

all:
Variant of Boolean type. If it is set to VARIANT_TRUE, all the records of the table are
returned. If not, all the records of the associated folder are returned. This means that only the filtered records are returned.
If no associated folder exists, this Boolean is ignored.
pRecords:
Address of pointer variable that receives the tabular data interface pointer. Upon
successful completion, *pRecords contains the requested interface pointer of the tabular data object.

Return Values
S_OK or E_INVALIDARG.
E_POINTER, if pRecords is NULL.

104

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Remarks
The list of available table names defined by Atoll can be found in the template (.mdb) file (see Technical Reference
Guide). Some other table names are available:

PREDICTIONS: to get pathloss matrices and signal level matrices.

ZONES: to get either the calculation zone or the focus zone. This table contains at most 2 records.

According to the purpose of your addin, and maybe its performance, you might prefer to fill a private map of all records
and then use this map for your features. The addin allows you to do that, but in some (rare) cases, this map is not up-todate: this can happen if a celltype has been changed for instance, all its TRGs are deleted.

Example
VBScript:

Dim records
Set records = app.ActiveDocument.GetRecords("Sites", True)
C++:

IDocumentPtr pDoc;
HRESULT hr = m_spApplication->get_ActiveDocument(&pDoc);
if (FAILED(hr)) return hr;
ITabularDataPtr pRecords;
hr = pDoc->GetRecords(_bstr_t(_T("Sites")), VARIANT_TRUE, &pRecords);
if (FAILED(hr)) return hr;

3.5.8.3.23

Redraw Method
Method that refreshes all items in the document.

HRESULT Redraw();
Parameters
None.

Return Values
S_OK.

Remarks
It has the same effect as the icon Refresh (F5) in Atoll GUI.

3.5.8.3.24

CenterMapOn Method
Centres map on the parameter point.

HRESULT CenterMapOn(double* ptx, double* pty);

Parameters
ptx, pty:
the same as in the document.

Double values that hold the coordinates of the point. The coordinate system must be

Return Values
S_OK.

3.5.8.3.25

GetRootFolder Method
Returns the root folder of all children belonging to one of the explorer tab.

HRESULT GetRootFolder(AtoRootType type,IChildFolder** pItem);

Parameters
type:

A Long value that tells Atoll which tab is requested (see 3.5.11.14 AtoRootType).

Item:
Address of pointer variable that receives the child folder interface pointer. Upon
successful completion, *pItem contains the requested interface pointer of the root child folder object.

Forsk 2007

AT260_DRG_E0

105

Developer Reference Guide

Return Values
S_OK or E_FAIL.
E_POINTER, if pItem is NULL.

Example
VBScript:

Dim geo
Set geo = app.ActiveDocument.GetRootFolder(1)
C++:

IDocumentPtr pDoc;
HRESULT hr = m_spApplication->get_ActiveDocument(&pDoc);
if (FAILED(hr)) return hr;
IChildFolderPtr pGeoTab;
hr = pDoc->GetRootFolder(atoGeo, &pGeoTab);
if (FAILED(hr)) return hr;

3.5.8.3.26

GetSortedSignals Method
This method is not directly connected to IDocument interface, but indirectly through QueryService mechanism.

IDocumentPtr* pDoc = activeDoc;

IServiceProviderPtr serv = pDoc;
ISignalsPtr sig;
hr = serv->QueryService(SID_SIGNALS,&sig);
GEORECT zone; grid.GetZone(zone);
VariantVector

sigDatas, serversDatas;

sigDatas.resize(par.m_depth); serversDatas.resize(par.m_depth);
IMultiGridDataPtr pServerNumbers, pSignals;
sig->GetSortedSignals(&zone, par.m_resolution ,par.m_cMin,par.m_cDiff
,par.m_depth, pTxs, &pSignals, &pServerNumbers);
(This code is extracted from the Best Signals Export add-in available upon request from support@forsk.com).

HRESULT GetSortedSignals(
[in]

GEORECT *zone,

[in]

double resolution,

[in]

double minSignalLevel,

[in]

double maxSignalDifference,

[in]

ULONG depth,

[in]

IUnknown pServers,

[out]

IMultiGridData **pSignals,

// Txs

[out]

IMultiGridData **pServerNumbers

);
Returns the nth Best Signal matrices.

Parameters
zone:

Describes the zone on which the signals are requested.

resolution:

Resolution of the best signals matrices to produce.

minSignalLevel:
the depth).

When the signal level goes below this value, it is ignored by the export (used to limit

maxSignalDifference:
When the difference between the max signal value on a bin and the current value
exceeds this value (positive), the current value is ignored.
depth:
Maximum number of potential signals wanted at a given point. If you want only the
best signal, set this parameter to 1.

106

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

pServers:

Pointer to the transmitters that must be taken into account in the calculation.

pSignals:
field levels.

Pointer to MultiGridData containing the n Best Signal Matrices. Contained values are

pServerNumbers:
Pointer to the MultiGridData containing the n Best Signal Matrices. Contained values
are index numbers of transmitters.

Return Values
S_OK.
No invalid entry is tested, so it must be tested outside and used very carefully.

Remarks
When no signal is available at a given point, the value at this point is set to -9999.
When no server is available at a given point, the value at this point is set to 0.

3.5.8.3.27

GetSortedServers Method
This method is not directly connected to IDocument interface, but indirectly through QueryService mechanism.

IDocumentPtr* pDoc = activeDoc;

IServiceProviderPtr serv = pDoc;
ISignalsPtr sig;
hr = serv->QueryService(SID_SERVERS,&sig);
GEORECT zone; grid.GetZone(zone);
VariantVector

sigDatas, serversDatas;

sigDatas.resize(par.m_depth); serversDatas.resize(par.m_depth);
IMultiGridDataPtr pServerNumbers, pSignals;
sig->GetSortedServers(&zone, par.m_resolution ,par.m_cMin,par.m_cDiff
,par.m_depth, pTxs, &pSignals, &pServerNumbers);
(This code is extracted from the Best Signals Export add-in available upon request from support@forsk.com).

typedef enum _BEST_SERVER_OPTION {

SIGNAL_STRENGTH = 0,
HCS_PRIORITY = 1,
EXTENDED_CELLS = 2,
RECOMPUTE_INVALID = 4
} _BEST_SERVER_OPTION;
HRESULT GetSortedServers(
[in]

GEORECT *zone,

[in]

double resolution,

[in]

double minSignalLevel,

[in]

double maxSignalDifference,

[in]

ULONG depth,

[in]

IUnknown pServers,

[in]

ULONG ulSortOption, // OR of BEST_SERVER_OPTIONs

[out]

IMultiGridData **pSignals,

[out]

IMultiGridData **pServerNumbers

// Txs

);
Returns the nth Best Signal matrices.

Parameters

Forsk 2007

zone:

Describes the zone on which the signals are requested.

resolution:

Resolution of the best signals matrices to produce.

minSignalLevel:
the depth).

When the signal level goes below this value, it is ignored by the export (used to limit

AT260_DRG_E0

107

Developer Reference Guide

maxSignalDifference:
When the difference between the max signal value on a bin and the current value
exceeds this value (positive), the current value is ignored.
depth:
Maximum number of potential signals wanted at a given point. If you want only the
best signal, set this parameter to 1.
pServers:

Pointer to the transmitters that must be taken into account in the calculation.

ulSortOption:

Combination of values taken from _BEST_SERVER_OPTION enumeration.

Sort options can be combined. For example, HCS_PRIORITY + EXTENDED_CELLS would change the order of the
signals and servers and return signals and servers according to HCS layers and extended cells. The sorting algorithm is
explained in the Best Signal Export tool documentation. The GetSortedServers method is the same as the GetSortedSignals method, if it is called with SIGNAL_STRENGTH as the sort option, i.e., HCS layers and extended cells are not taken
into account.
pSignals:
field levels.

Pointer to MultiGridData containing the n Best Signal Matrices. Contained values are

pServerNumbers:
Pointer to the MultiGridData containing the n Best Signal Matrices. Contained values
are index numbers of transmitters.

Return Values
S_OK.
No invalid entry is tested, so it must be tested outside and used very carefully.

Remarks
When no signal is available at a given point, the value at this point is set to -9999.
When no server is available at a given point, the value at this point is set to 0.

3.5.8.4

IDocument2 Interface
Adds a pathloss calculation feature to IDocument, a generic capability to support future functions through a GetService
mechanism and a feature of saving field strength values to a binary file.

Object
Document

3.5.8.4.1

Function

Property (P)
Method (M)

HRESULT RunPathloss (VARIANT_BOOL,VARIANT_BOOL)

HRESULT GetService (BSTR, IDispatch**)

RunPathloss Method
Computes only pathloss values without the need to have a predefined study created.

HRESULT RunPathloss(VARIANT_BOOL allTx, VARIANT_BOOL forced);

Parameters
allTx:
When VARIANT_TRUE, the computation will be made for all active transmitters in the
table. When VARIANT_FALSE, only filtered transmitters will be computed.
forced:
When VARIANT_TRUE, computation will be forced even for transmitters having available valid results. When VARIANT_FALSE, computation will be made only for transmitters having unavailable or invalid
results.

Return Values
S_OK.
The Return Values of standard ATL AtlReportError function, in case of error.
Please see the online (or MSDN) documentation page of AtlReportError to obtain the list of possible values.

Remarks
This API function corresponds to the menu commands Calculate path loss matrices and Force path loss matrix calculation available in the Calculations sub-menu of the Transmitters folder.

3.5.8.4.2

GetService Property
Gets a service provider inheriting from IDispatch type by giving its predefined name.

HRESULT GetService (BSTR name, IDispatch** pdisp)

108

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Parameters
name:
Name of the service. The name can be either a standard character string or the ClsID
of a component registered on the machine.
pdisp:
service.

Address of an IDispatch pointer receiving the object that implements the requested

Return Values
S_OK.
E_POINTER, if pdisp is NULL.
E_NOINTERFACE, if no object implementing the requested interface were found.

Remarks
The service provider inherits from Idispatch, which permits not only add-ins but also macros to use this interface. Currently
there is only one service provider implemented (see 3.5.8.7 IResultFileProvider interface).

3.5.8.5

IDocument3 Interface
Adds an export capability of configuration files to IDocument.

3.5.8.5.1

Object

Function

Property (P)
Method (M)

Document

HRESULT ExportConfig (BSTR content, BSTR file)

ExportConfig Method
Exports the current configuration from the document to an output file, according to the content parameter.

HRESULT ExportConfig(BSTR content, BSTR file);

Parameters
content:

GEO corresponds to the configuration of geographic files only.

GEO+ZONES corresponds to the configuration of geographic files + calculation

zones (computation+focus)
FULL corresponds to a full export of the configuration file.
file:

Name of the file into which the configuration must be exported

Return Values
S_FALSE in case of error.
E_NOTIMPL if content is set to something other than GEO, GEO+ZONES or FULL.
S_OK in case of successful operation.

3.5.8.6

IDocument4 Interface
This interface gives the possibility to invoke arbitrary commands on a document. You have to know the command names.

Forsk 2007

Object

Function

Property (P)
Method (M)

Document

HRESULT GetCommandDefaults([in] const BSTR bstrCommandName, [out, retval] IPropertyContainer **ppParameters);

HRESULT InvokeCommand([in] const BSTR bstrCommandName,

[in, unique, defaultvalue(NULL)] IPropertyContainer
*pParameters, [out, retval] IPropertyContainer **ppResults);

HRESULT RadiatedPowerUnit([out, retval] enum AtoRadiatedPowerUnit *pVal);

HRESULT RadiatedPowerUnit([in] enum AtoRadiatedPowerUnit aNewVal);

HRESULT AntennaGainUnit([out, retval] enum AtoAntennaGainUnit *pVal);

HRESULT AntennaGainUnit([in] enum AtoAntennaGainUnit
aNwVal);

AT260_DRG_E0

109

Developer Reference Guide

HRESULT HeightOffsetUnit([out, retval] enum AtoHeightOffsetUnit *pVal);

HRESULT HeightOffsetUnit([in] enum AtoHeightOffsetUnit
aNewVal);

3.5.8.6.1

GetCommandDefaults Property
Gets current default parameters specific to a command.

HRESULT GetCommandDefaults([in] const

IPropertyContainer **ppParameters);

BSTR

bstrCommandName,

[out,

retval]

Parameters
bstrCommandName:

Parameters retreived are parameters specific to bstrCommandName.

ppParameters:
eters, is retreived.

Address of the interface pointer where the property container, holding default param-

Return Values
E_NOTIMPL, if there are no default parameters for this command.
S_OK, if the parameter was successfully retreived.

3.5.8.6.2

InvokeCommand Property
Invokes a command.

HRESULT InvokeCommand([in] const BSTR bstrCommandName, [in, unique, defaultvalue(NULL)] IPropertyContainer *pParameters, [out, retval] IPropertyContainer
**ppResults);
Parameters
bstrCommandName:
pParameters:

Name of the command to invoke.

Parameters needed to carry out the command.
If set to NULL, default parameters for the command will be used.

ppResults:

Results of the command invokation.

*ppResults will be set to NULL if the command gives no results.

Return Values
E_NOTIMPL, if the command is not supported.
S_OK, if the command was successfully carried out.
*ppResults will contain the command results if applicable.

3.5.8.6.3

RadiatedPowerUnit Property
Property that sets or gets the current radiated power unit.

HRESULT RadiatedPowerUnit([out, retval] enum AtoRadiatedPowerUnit *pVal);

HRESULT RadiatedPowerUnit([in] enum AtoRadiatedPowerUnit aNewVal);
Parameters
pVal:
PowerUnit).

Address of an integer variable that receives the unit (see 3.5.11.11 AtoRadiated-

aNewVal:

Integer containing the unit.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.6.4

AntennaGainUnit Property
Property that sets or gets the current antenna gain unit.

HRESULT AntennaGainUnit([out, retval] enum AtoAntennaGainUnit *pVal);

HRESULT AntennaGainUnit([in] enum AtoAntennaGainUnit aNewVal);

110

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Parameters
pVal:
GainUnit).

Address of an integer variable that receives the unit (see 3.5.11.12 AtoAntenna-

aNewVal:

Integer containing the unit.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.6.5

HeightOffsetUnit Property
Property that sets or gets the current height offset unit.

HRESULT HeightOffsetUnit([out, retval] enum AtoHeightOffsetUnit *pVal);

HRESULT HeightOffsetUnit([in] enum AtoHeightOffsetUnit aNewVal);
Parameters
pVal:
GainUnit).

Address of an integer variable that receives the unit (see 3.5.11.13 AtoAntenna-

aNewVal:

Integer containing the unit.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.7

IResultFileProvider Interface
Specific service provider enabling the field strength results of a transmitter, including high and low resolution results, to be
computed and stored in a binary .bil file.

3.5.8.7.1

Object

Function

Property (P)
Method (M)

ResultFileProvider

HRESULT Build (BSTR, BSTR, long, long, long, long,

long, long*, long*)

Build Method
Service provider returned by a call to GetService on IDocument2 interface with the name SIGNAL as first parameter.
Builds the composite signal matrix of one transmitter and stores the result in a file.

HRESULT Build(BSTR fileName, BSTR txName, long step, long xmin, long xmax, long
ymin, long ymax, long* xorig, long* yorig);
Parameters
fileName:

Name of the file in which the signal results will be saved.

txName:

Name of the transmitter whose signal results are requested.

step:
Resolution of the matrix in meters. This value may be different from the main and
extended pathloss matrices resolutions of the transmitter.
xmin:

X origin of the zone on which the results are requested.

xmax:

X end limit of the zone on which the results are requested.

ymin:

Y origin of the zone on which the results are requested.

ymax:

Y end limit of the zone on which the results are requested.

xorig:
Pointer to the actual X origin of the results (depends on the calculation radii of the
transmitter, the general computation zone and so on).
yorig:
Pointer to the actual Y origin of the results (depending on the calculation radii of the
transmitter, the general computation zone and so on).

Return Values
S_OK.
E_ABORT, if the user interrupts the calculation.
E_POINTER, if xorig or yorig are NULL.

Forsk 2007

AT260_DRG_E0

111

Developer Reference Guide

Remarks
The parameter name of GetService function can either be SIGNAL or the CLSID of this class: L"{B02A59E4-0F56-4FD1A71A-454576912A20}".
Currently only ASCII .txt file format is supported. The values surrounding the computed ones are set to FLT_MAX.

3.5.8.8

ITabularData Interface
Variant type is used to put or get a value from a tabular data. Mostly a simple VariantChangeType will assure you to safely
get the information you want in a more friendly type. However, some values are more complex and need some additional
treatments.

Object
TabularData

HRESULT AddNew()
HRESULT ColumnCount(long*)

HRESULT Delete(long)

HRESULT Edit(long)

HRESULT
long*)

3.5.8.8.1

Property (P)
Method (M)

Function

Find(long,

VARIANT,

AtoCompareOp,

VARIANT,

HRESULT FindPrimaryKey(VARIANT val, long*)

HRESULT GetFormattedValue(long, VARIANT, BSTR *)

HRESULT GetPrimaryKey(long, VARIANT*);

HRESULT GetValue(long, VARIANT, VARIANT*)

HRESULT RowCount(long*)

HRESULT SetValue(VARIANT, VARIANT)

HRESULT Update(long*);

ColumnCount Property
Property that gets the number of column of the tabular data. This property is read only.

HRESULT ColumnCount([out, retval] long *pVal);

Parameters
pVal:

Address of the long integer that receives the number of columns.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

Remarks
This number does not include the RECORD_ID column. If a table TABLE1 is defined by FIELD1, FIELD2 and FIELD3,
ColumnCount returns 3.

3.5.8.8.2

RowCount Property
Read-only property that gets the number of rows (records) of the tabular data.

HRESULT RowCount(long *pVal);

Parameters
pVal:

Address of the integer that receives the number of rows.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

Remarks
This number does not include the columns name row. If a table TABLE1 has no record, it returns 0. GetValue(0, 1) returns
FIELD1, which is the name of the column number 1 (read in row number 0). GetValue(0, 0) returns RECORD_ID, which

112

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

is the name of the column number 0 (read in row number 0). GetValue(1, 1) returns anyValue , which is the value for
column FIELD1 (number 1) in row number 1.

3.5.8.8.3

Edit Method
Method that informs Atoll which record will be modified.

HRESULT Edit(long iRow);

Parameters
iRow:

Long value containing the number (index) of the record.

Return Values
S_OK, if 0 < iRow GetRowCount() and no record is currently being edited or added,
Else E_INVALIDARG.
Notes:

3.5.8.8.4

Dont forget to call this method before a call to SetValue and to call Update to end the changes in the
record.

AddNew Method
Method that adds a new empty record in the tabular data.

HRESULT AddNew();
Parameters
None.

Return Values
S_OK, if the tabular data accepts new records and no record is currently being edited or added,
Else E_FAIL.
Notes:

3.5.8.8.5

Dont forget to call this method before a call to SetValue and to call Update to end the initialisation of the
records fields.

Update Method
Method that ends the editing of a record.

HRESULT Update(long *iRow);

Parameters
iRow:
Address of the Long receiving the number of the row of the record. If the method Edit
started the editing, the same iRow as in Edit is returned. If it was AddNew method, the number is the row number where
the new record has been added.

Return Values
S_OK, if a record has been edited or added otherwise E_FAIL.
E_POINTER, if iRow is NULL.

Remarks
This method must be called once after each Edit and AddNew. Editing one record after another without updating the previous one will throw an error. Edit/Update cannot be mixed up for different record, neither can be AddNew/Update.

3.5.8.8.6

Delete Method
Method that deletes a record.

HRESULT Delete(long iRow);

Parameters
iRow:

Forsk 2007

Long containing the number of the row of the record which must be deleted.

AT260_DRG_E0

113

Developer Reference Guide

Return Values
S_OK, if iRow is a valid row number and if the deletion is allowed,
Else E_INVALIDARG.

Remarks
A valid iRow number is any integer, such that 0 < iRow RowCount(). Deletion can fail if a record is related to another one
(an antenna cannot be deleted if being by a transmitter).
Be careful when using this method with sub-tables, as for instance TRANSMITTERS table and TRXs table. If you delete
one TRX with the toolkit, the field TRX_NUMBER might be erroneous. The workaround to avoid this is to edit records in
the TRXs table.

3.5.8.8.7

GetValue Method
Method that gets the value of a column at a given row.

HRESULT GetValue(long iRow, VARIANT iCol, VARIANT *pVal);

Parameters
iRow:

Long containing the number of the row of the record.

iCol:

Integer or string that defines the column from which you requested the value.

pVal:

Address of the variant that receives the value.

Return Values
S_OK, if iRow and iCol are valid numbers,
Else E_ INVALIDARG.

Remarks
A valid iRow number is any integer, such that 0 iRow RowCount(). A valid iCol is either an integer such that 0 iCol ColumnCount() or a string containing the name of an existing column. The column names are not case sensitive.
You do not have to Edit a record before reading its field values. The returned value is a Variant, which means that in
VBScript, you can generally use simple types instead. While in C++, use VariantChangeType to make sure the conversion
towards a friendly type is valid. For complex returned values, we recommend using C++.

Example
VBScript:

Set sites = app.ActiveDocument.GetRecords(Sites)

For i = 1 To sites.ColumnCount
colName = sites.GetValue(0, i)
Next i
C++:

IDocumentPtr pDoc;
HRESULT hr;
if (FAILED(hr = (m_spApplication->get_ActiveDocument(&pDoc))))
return hr;
ITabularDataPtr pRecords;
if (FAILED(hr =
(pDoc->GetRecords(_bstr_t(_T("Sites")), VARIANT_TRUE,

&pRecords))))

return hr;
long nCol = 0;
pRecords->get_ColumnCount(&nCol);
for (long i = 0; i <= nCol; ++i)
{
_variant_t value;
pRecords->GetValue(0, _variant_t(i + 1), value);
}

114

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Reading the main contour of the focus zone in VBScript:

Public Sub ReadZone()

Set doc = ActiveDocument
Set zones = doc.GetRecords("Zones", true)
row = zones.Find(1, "NAME", atoEQ, "FocusZone")
pts = zones.GetValue(row, "POINTS")
if (IsArray(pts)) then
nb = UBound(pts, 1) - LBound(pts, 1) + 1
For i = 0 To nb-1
ptx = pts (i,0)
pty = pts (i,1)
MsgBox "Pts("+CStr(i)+") = " + CStr(ptx) + ", " + CStr(pty) + "..."
Next
Else
MsgBox "Pb: not array"
End if
End Sub
For an example of reading a matrix, see 3.5.8.8.13.
For an example of reading antenna signatures, see 3.5.8.8.16.

3.5.8.8.8

SetValue Method
Method that sets the value of a column for the record being edited or added.

HRESULT SetValue(VARIANT iCol, VARIANT newVal);

Parameters
iCol:

Integer or string that defines the column you want to set.

newVal:

Variant containing the value.

Return Values
S_OK, if iCol is valid and if newVal type matches the column type,
Else E_ INVALIDARG.

Remarks
A valid iCol is either an integer such that 0 < iCol ColumnCount() or a string containing the name of an existing column.
The column names are not case sensitive.
You must have previously called Edit or AddNew to set the row number before writing the field value. The new value is a
Variant, which means that in VBScript, you can generally use simple types instead. While in C++, use the _variant_t type
to initialize the value. For complex values, we recommend using C++.
If this method is used for a large number of records, it is recommended to get the column numbers beforehand and then
to use the SetValue method with this number and not with a variant of type VT_BSTR. This will run faster. To get the
column number, use the method GetValue with a row number set to 0.

Example
This example increments all the TX Losses by one for each transmitter inside the active document.
VBScript:

Dim transmitters
Dim doc
Dim i
Dim txLosses
Set doc = app.ActiveDocument
Set transmitters = doc.GetRecords(Transmitters)
For i = 1 To transmitters.RowCount
txLosses = transmitters.GetValue(i, TXLOSSES)

Forsk 2007

AT260_DRG_E0

115

Developer Reference Guide

transmitters.Edit(i)
transmitters.SetValue(TXLOSSES, txLosses + 1)
transmitters.Update()
Next i
Instead, we could have used:

For i = 1 To transmitters.RowCount
txLosses = transmitters.GetValue(i, 14)
transmitters.Edit(i)
transmitters.SetValue(14, txLosses + 1)
transmitters.Update()
Next i
C++:

IDocumentPtr pDoc;
HRESULT hr;
if (FAILED(hr = (m_spApplication->get_ActiveDocument(&pDoc))))
return hr;
ITabularDataPtr pRecords;
if (FAILED(hr =
VARIANT_TRUE, &pRecords))))

(pDoc->GetRecords(CComBSTR(_T("Transmitters")),

return hr;
long nRows = 0;
pRecords->get_RowCount(&nRow);
_variant_t vCol = long(14);
for (long i = 0; i < nRow; ++i)
{
_variant_t vLoss;
pRecords->GetValue(i+1, vCol, &vLoss);
if (FAILED(hr = VariantChangeType(&vLoss, &vLoss, 0, VT_R8)))
return hr;
double losses = vLoss;
vLoss = losses + 1.;
pRecords->Edit(i+1);
if (FAILED(hr = pRecords->SetValue(vCol, vLoss)))
return hr;
pRecords->Update();
}
Instead, we could have written:

_variant_t vCol = LTXLOSSES;

Updating the main contour of the focus zone in VBScript:

Public Sub WriteZone()

Set doc = ActiveDocument
Set zones = doc.GetRecords("Zones", true)
row = zones.Find(0, "NAME", atoEQ, "FocusZone")
Dim pts(4,2)
pts(0, 0) = 555000
pts(0, 1) = 2188000
pts(1,0)

116

= 600000

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

pts(1,1)

= 2188000

pts(2,0)

= 600000

pts(2,1)

= 2140000

pts(3,0)

= 555000

pts(3, 1) = 2140000
zones.Edit row
zones.SetValue "POINTS", pts
zones.Update
End Sub

3.5.8.8.9

GetPrimaryKey Method
Method that gets the value of the primary key for a given row number.

HRESULT GetPrimaryKey(long iRow, VARIANT* pVal);

Parameters
iRow:

Integer that defines the row number.

pVal:

Variant that receives the value.

Return Values
S_OK, if iRow is valid,
Else E_INVALIDARG.
E_POINTER, if pVal is NULL.

Remarks
A valid iRow number is an integer such that 0 < iRow RowCount(). Most of the tabular data have a specific primary key
(for example, a sites name). If no primary key is defined, the RECORD_ID is returned. When the key is made of several
columns, the type of the output variant is VT_ARRAY|VT_VARIANT.

3.5.8.8.10

FindPrimaryKey Method
Method that searches the record whose primary key equals the input value and returns the row number of the record found.
Otherwise, returns 1.

HRESULT FindPrimaryKey(VARIANT val, long* iRow);

Parameters
val:

Variant containing the value of the key being searched.

iRow:

Integer that receives the row number corresponding to the record (-1 if not found).

Return Values
S_OK.
E_POINTER, if iRow is NULL.

Remarks
When the key comprises several fields, the input variant must be of type VT_ARRAY|VT_VARIANT.

3.5.8.8.11

Find Method
Method that searches for a value in column iCol starting at iRowStart. Upon successful completion, the row number with
the matching value is returned in iRow.

HRESULT Find(long iRowStart,

long* iRow);

VARIANT vCol, AtoCompareOp op, VARIANT value,

Parameters

Forsk 2007

iRowStart:

Position of the first row at which the search operation begins.

vCol:

Index or Name of the column concerned with the search.

op:
See 3.5.11.7 AtoCompareOp.

An integer that specifies the kind of search (equal, greater, less than, equal to, etc).

AT260_DRG_E0

117

Developer Reference Guide

value:

The field value being searched.

iRow:
record is found.

The row number of the first record matching the search criteria. Contains 1 if no

Return Values
S_OK.
E_INVALIDARG, if iRowStart is incorrect.
E_POINTER, if iRow is NULL.

Remarks
Patch iRowStart inside a loop in order to scan several records matching the search criteria.
This method should be used only for a few searches, because on the Atoll side, this method scans the records one after
the other and can be very time consuming.
If your code allows, try to swap your loops and use FindPrimaryKey, or keep a collection (map) of all records and write
your own filter.

Example
In this example, we search for all transmitters whose TxLosses (column number 14) is equal to 2 and we change its value
to 3.
VBScript:

Dim transmitters
Dim iRow
Set transmitters = app.ActiveDocument.GetRecords(Transmitters)
iRow = 1
While iRow > -1
iRow = transmitters.Find(iRow, 14, atoEQ, 2)
transmitters.Edit(iRow)
transmitters.SetValue(iRow, 14, 3)
transitters.Update
Wend

3.5.8.8.12

GetFormattedValue Method
Method that returns a field value formatted as a string.

HRESULT GetFormattedValue(long iRow, VARIANT iCol, BSTR *pVal);

Parameters
iRow:

Long value containing the number of the row of the record.

iCol:

Integer or string that defines the column from which the value is requested.

pVal:

Address of the string receiving the value.

Return Values
S_OK, if iRow and iCol are valid numbers,
Else E_INVALIDARG.
E_POINTER, if pVal is NULL.
If the column cannot be converted into a string type, returns E_FAIL.

Remarks
A valid iRow number is an integer such that 0 iRow RowCount(). A valid iCol is either an integer such that 0 iCol ColumnCount() or a string containing the name of an existing column. The column names are not case sensitive.

3.5.8.8.13

Reading Pathloss Matrices

(Reading pathloss matrices uses VT_UNKNOWN type.)
To read the pathloss matrix, read the field named PATHLOSS of the Predictions TabularData object. To read the signal
level matrix, read the field named SIGNAL.
Below is a brief example of extracting signal information. We suppose that at least one transmitter exists with a valid cell.

118

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

HRESULT CMyTool::ReadSignal(IDocument* pDoc)

{
SetErrorInfo(0, NULL); // to reset previous errors
try

// Well throw _com_error when calls to Atoll fail.

{
// just information to follow the add-in execution
m_spApplication->LogMessage(_bstr_t(_T("MyTool:ReadSignal entered")), atoInfo);
HRESULT hr = S_OK;
// Get all the predictions
ITabularDataPtr pPredictions;
if (FAILED(hr = (pDoc->GetRecords(CComBSTR(_T("Predictions")),
VARIANT_TRUE, &pPredictions))))
_com_issue_errorex(hr, pDoc, __uuidof(pDoc));
// Get Signal field for 1st record
_variant_t sigKey = L"Signal";
_variant_t vSignal;
if (FAILED( hr = (pPredictions ->GetValue(1, sigKey, &vSignal))))
_com_issue_errorex(hr, pPredictions, __uuidof(pPredictions));
// Extract a GridData from the field
IGridDataPtr iGrid = V_UNKNOWN (&vSignal);
// Read the grid data properties
GEOPOINT pt;
ULONG nx, ny;
double rexX,

resY;

PIXEL_TYPE pixType;
if ((FAILED(hr =

(iGrid->GetDimension(&pt, &nx, &ny, &rexX, &resY))))

|| (FAILED(hr =

(iGrid->GetPixelType(&pixType)))))

_com_issue_errorex(hr, iGrid, __uuidof(iGrid));

// Extract a sub-grid
_variant_t grid;
if (FAILED(hr =

(iGrid->ExtractSubGrid( 0, 0, nx, ny, &grid))))

_com_issue_errorex(hr, iGrid, __uuidof(iGrid));

if (grid.vt != (VT_ARRAY | VT_R4) || SafeArrayGetDim(grid.parray)!=2)
return E_FAIL;
// Use SafeArray to extract float values from the variant
long lx, ly, ux, uy;
SafeArrayGetLBound(grid.parray,1,&lx);
SafeArrayGetLBound(grid.parray,2,&ly);
SafeArrayGetUBound(grid.parray,1,&ux);
SafeArrayGetUBound(grid.parray,2,&uy);
if (lx!=0 || ly!=0 || ux!=long(nx-1) || uy!=long(ny-1))
return Error("Grid size is not correct", __uuidof(IAddin));
// vals is the friendly result you will use.
float* vals = new float[nx * ny];
UINT n =0;
for (UINT j=0; j < ny; j++)
{
float* pdata;
long idx[]= {0,j};
SafeArrayPtrOfIndex(grid.parray,idx,(void**) &pdata);

Forsk 2007

AT260_DRG_E0

119

Developer Reference Guide

for (UINT i=0; i < nx; i++)

vals[n++] = pdata[i];
}
delete[] vals;
return hr;
}
catch(_com_error& e) {return Error(LPOLESTR(e.Description()), __uuidof(IAddin), e.Error());}
catch (...) {return E_UNEXPECTED; }
}
Notes:

3.5.8.8.14

The previous code reads the first record of the prediction tabular data (pPredictions ->GetValue(1, sigKey,
&vSignal)). A more realistic code would be that reads a given matrix and not only the first one, which is not
the first record of the transmitters tabular data. One solution would be to loop through all the transmitters
whose matrices you require, to read its name and to call the method Find on the prediction data to reach
the record where the field TX_ID equals this name. Then for that row, read the PATHLOSS field. This
method may be used for a small number of transmitters but not for a large number because it would be very
time consuming.

If you write your loop in another way, your code should be more efficient: scan each record of prediction,
read the TX_ID field value, then use the method FindPrimaryKey on the TRANSMITTERS table to find the
transmitter with this key. Searching a record using its primary key is faster than searching a record through
any ordinary field.

It is possible to read the full pathname of the shared results through the API. To obtain this, just access the
field SHARED_RESULTS_FOLDER in the NETWORKS table.

Editing Computation or Focus Zones

The ZONES table contains only 2 record types, the computation zone and the focus zone. An add-in may read and edit
the points of both zones. Editing the points of a zone means modifying it or creating it if there are currently no points associated with it. All points are set or got within a 2-dimensional array of variants.
Atoll 2.4.0 and later support multiple polygons as focus zones. The focus zone is a multiple polygon zone composed of
several contours assigned to one or more polygons. This description allows for modelling complex focus zones, including
even focus zones with holes.

Reading a Zone
ITabularDataPtr zones;
doc->GetRecords(_bstr_t(L"ZONES"),_variant_t(true),&zones);
_variant_t NAME = bstr_t("NAME");
_variant_t POINTS = bstr_t("POINTS");
_variant_t CONTOUR_NUM = bstr_t("CONTOUR_NUM");
_variant_t POLYGON_NUM = bstr_t("POLYGON_NUM");
long count_;
zones->get_RowCount(&count_);
for(i=1;i<=count;i++)
{
_variant_t name_;
zones->GetValue(i,NAME, &name_);
//you can test here for "FocusZone" or "ComputationZone"
_variant_t points_;
zones->GetValue(i,POINTS, &points_); //reading points array
if (points_.vt == (VT_ARRAY|VT_VARIANT))
{
COleSafeArray sa_;
sa_.Attach(points_);
long minRow_ = 0, maxRow_ = 0;
sa_.GetUBound(1, &maxRow_);

120

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

sa_.GetLBound(1, &minRow_);
long index[2];
_variant_t x,y;
for(long k = minRow_; k <= maxRow_; k++) //reading each point
{
index[0] = k;
index[1] = 0;
sa_.GetElement(index, &x);
index[1] = 1;
sa_.GetElement(index, &y);
}
}
_variant_t contourNum_;
zones->GetValue(i,CONTOUR_NUM, &contourNum_); //get the contour num
_variant_t polygonNum_;
zones->GetValue(i,POLYGON_NUM, &polygonNum_);

//get the polygon num

}
Writing a Zone
//DROP ALL FOCUS POLYGONS
for(i = count_; i >= 2; i--)
{
_variant_t name_;
//read the name ("FocusZone" or "ComputationZone")
zones->GetValue(i, NAME, &name_);
if (CString(name_) == "FocusZone")
HRESULT hr = zones->Delete(i);
}
//ADD THESE NEW TWO POLYGONS IN THE FOCUS ZONE
static float Poly1gone1_[] = {1000,3000,1500,2500,1000,4500};
static float Poly1gone2_[] = {5000,7000,5500,6500,5000,8500,10000,8500};
static float* polygones_[] = {Poly1gone1_,Poly1gone2_};
for (int poly_=0 ; poly_<sizeof(polygones_)/sizeof(float*) ; poly_++)
{
HRESULT hr=zones->AddNew();
_variant_t name_ = CString("FocusZone");
zones->SetValue(NAME, name_);
_variant_t contourNum_ = int(0);
zones->SetValue(CONTOUR_NUM, contourNum_);

//write contour number

_variant_t polygonNum_ = int(poly_);

zones->SetValue(POLYGON_NUM, polygonNum_);

//write zone number

COleSafeArray array;
int size_ = 0;

//number of points

if (poly_ == 0)

size_= sizeof(Poly1gone1_)/sizeof(float)/2;

else

size_= sizeof(Poly1gone2_)/sizeof(float)/2;

ULONG dim[2] = {size_, 2};

array.Create(VT_VARIANT, 2, dim);
long idx[2];
VARIANT vv; vv.vt

= VT_R8;

for (idx[0] = 0; idx[0] < size_; (idx[0])++)

Forsk 2007

AT260_DRG_E0

121

Developer Reference Guide

{
idx[1] = 0;
vv.dblVal = polygones_[poly_][2*idx[0]];
array.PutElement(idx, &vv);
idx[1] = 1;
vv.dblVal = polygones_[poly_][2*idx[0]+1];
array.PutElement(idx, &vv);
}
VARIANT points2_ = array.Detach();
_variant_t value;
value.vt

value.parray =

points2_.vt;
points2_.parray;

points2_.vt

VT_EMPTY;

zones->SetValue(POINTS, value);
long ri_;
zones->Update(&ri_);
}
return TRUE;
}

3.5.8.8.15

Editing Repeaters
Repeaters properties are split between two tables in Atoll data structure. The properties related only to the repeater are
stored in the REPEATERS table, while other properties are stored in the TRANSMITTERS table. To learn more about Atoll
database structure, refer to the Technical Reference Guide.
To read the EIRP property of a repeater, get a Repeaters tabular data" and reach the right record. Then use the GetValue
method requesting for the EIRP column (or _best practice_ its column number).
To change the transmitting antenna of the same repeater, get a Transmitters tabular data" and reach the record with the
same ID (using FindPrimaryKey) as the repeater you are working on. Use the SetValue method for the ANTENNA_NAME
column (or _best practice_ its number).
Since the primary key of the REPEATERS table is also the primary key of the TRANSMITTERS table, you can also loop
through the TRANSMITTERS table and then use FindPrimaryKey on the REPEATERS table. If the row number returned
by this method is -1, then this id corresponds to a pure transmitter and not a repeater.
Reading the pathloss matrix of a repeater is exactly the same as reading the pathloss matrix of a pure transmitter. So as
advised in 3.5.8.8.13, you should first scan the PREDICTION table and use FindPrimaryKey on the REPEATERS table to
reach the repeaters properties (just as you used FindPrimaryKey to reach the transmitter's properties).

3.5.8.8.16

Reading Antenna Signatures

The GetValue method can be used to read antenna signatures of all the antennas associated with any given transmitter.
These can be the main and the secondary antennas both. The following example shows how to do this.

Public Sub AntennaSignatures()

Set App = Application
Set transmitters = App.ActiveDocument.GetRecords("Transmitters", False)
For nbRow = 1 to

transmitters.RowCount

nameTx = transmitters.GetValue(nbRow, "TX_ID")

antennaSignature = transmitters.GetValue(nbRow, "_ANTENNA_SIGNATURE")
LogMessage "Transmitter :" + CStr(nameTx) + " ; Signature antenne : " +
CStr(antennaSignature), 0
Next
End sub

3.5.8.8.17

Accessing Transmitter EIRPs and Antenna Diagrams

The GetValue method can be used to access transmitter antenna diagrams. This is done by querying the column
_RADIO_TRANSMITTER in the transmitters table:

ITabularDataPtr pTransmitters;

122

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

_variant_t v;
IRadioTransmitter3Ptr pRadioTransmitter;
pTransmitters->GetValue(1, _variant_t(L_RADIO_TRANSMITTER), &v);
IRadioTransmitter3Ptr pRadioTransmitter;
pRadioTransmitter = V_UNKNOWN(&v);
IRadioTransmitter3 is part of the propagation model API.

3.5.8.8.18

Reading Data Tab Folders (Simulations)

This example shows how you can read the results of simulations. The limits on the number of rows and the number of
columns in this example are only sample values to restrict the display to a certain number of result values.

sub main
Set data = ActiveDocument.GetRootFolder(0)
ScanFolders data
end sub
sub scanValues (values)
MsgBox values.RowCount
MsgBox values.ColumnCount
maxLine=values.RowCount
if values.RowCount > 2 then
maxLine=6
end if
maxCol=values.ColumnCount
if values.ColumnCount>5 then
maxCol=5
end if
For j = 0 To maxLine
For i = 89 To 89+maxCol
colName = values.GetValue(j, i)
If IsNull(colName) Then
MsgBox "vide"
else
MsgBox colName
end if
Next
Next
end sub
Function ScanFolders (it)
For each item In it
If item.ObjectKind = "{CDDF1E1D-1963-4D80-A057-D23A19570984}" then
MsgBox "Simulations found"
ScanFolders item
end if
if item.ObjectKind = "{AF5E2B98-1D54-48FA-89C5-8BFA2936ABF2}" then
MsgBox "Simulation group found"
set groupsimud= item.dispatch
set mean=groupsimud.MeanSimulation
set meancells=mean.cells
scanvalues meancells
set meansites=mean.sites

Forsk 2007

AT260_DRG_E0

123

Developer Reference Guide

scanvalues meansites
set meanmobiles=mean.mobiles
scanvalues meanmobiles
set std=groupsimud.StdDevSimulation
set stdcells=std.cells
scanvalues stdcells
set stdsites=std.sites
scanvalues stdsites
set stdmobiles=std.mobiles
scanvalues stdmobiles
ScanFolders item
end if
if item.ObjectKind = "{095C5D90-96F1-4BA8-85BB-B2F990AC2DD9}" then
MsgBox "Simulation Found"
set simud = item.dispatch
set cells = simud.Cells
scanvalues cells
set sites = simud.Sites
scanvalues sites
set mobiles = simud.mobiles
scanvalues mobiles
end if
Next
end function

3.5.8.8.19

Reading Data Tab Folders (CW Measurements and Test Mobile Data)
This example shows how you can read the data available in the CW Measurements and Test Mobile Data folders.

function ScanFolders
Set data = ActiveDocument.GetRootFolder(0)
For each item In data
LogMessage item.Name
LogMessage item.ObjectKind
If item.ObjectKind = "{41413C4A-C9DE-43DD-A917-612A0AF198FC}" then
LogMessage "CW found"
For each it in item
LogMessage "it.ObjectKind : " + it.ObjectKind
For each meas in it
LogMessage "meas.ObjectKind : " + meas.ObjectKind
LogMessage "meas.Name : " + meas.Name
Set mes = meas.dispatch
Set vals =

mes.Values

LogMessage "vals.RowCount : " + CStr(vals.RowCount)

LogMessage "vals.ColumnCount : " + CStr(vals.ColumnCount)
For j = 0 To vals.RowCount
For i = 1 To Vals.ColumnCount
colName = Vals.GetValue(j, i)
If IsNull(colName) then
LogMessage "vide"
else
LogMessage CStr(colName)

124

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

end if
Next
Next
Next
Next
end if
if item.ObjectKind = "{21C11380-D8CF-4902-B622-763522AD9FC4}" then
LogMessage "Drive test found"
For each it in item
LogMessage "it.ObjectKind : " + it.ObjectKind
LogMessage "it.Name : " + it.Name
Set mes = it.dispatch
Set vals =

mes.Values

LogMessage "vals.RowCount : " + CStr(vals.RowCount)

LogMessage "vals.ColumnCount : " + CStr(vals.ColumnCount)
For j = 0 To vals.RowCount
For i = 1 To Vals.ColumnCount
colName = Vals.GetValue(j, i)
if IsNull(colName) then
LogMessage "vide"
else
LogMessage CStr(colName)
end if
Next
Next
Next
end if
Next
end function

3.5.8.9

ITabularData2 Interface
This interface adds a filter feature to data tables and provides the possibility to access the list of differences between databases through the API. These are the differences listed in the Archive dialog of Atoll, which can be submitted through an
external process using this interface.
ITabularData2 gives access to the original data as retrieved by the latest refresh from the database. it does not allow to
show differences or solve conflicts between the data in the ATL document and the database.
The ITabularData2 interface cannot be used to retrieve or get information about deleted records. In a later version of Atoll,
it will be possible to determine the records which have been deleted.
Original values and the record status are not stored in the database. They are stored in the Atoll document. Atoll compares
these values when it displays the modifications in the archive dialogue.

Object
TabularData2

Forsk 2007

Function

Property (P)
Method (M)

HRESULT CancelUpdate()

HRESULT ColumnNumber([in] VARIANT vColName, [out,

retval] long *pCol)

HRESULT CanEdit([out, retval] VARIANT_BOOL *pVal)

HRESULT CanAddNew([out, retval] VARIANT_BOOL *pVal)

HRESULT CanFilterSort([out, retval] VARIANT_BOOL *pVal)

HRESULT Filter([in] VARIANT vCriteria)

HRESULT Filter([out, retval] VARIANT *pvCriteria)

HRESULT Sort([in] VARIANT vCriteria)

HRESULT Sort([out, retval] VARIANT *pvCriteria)

AT260_DRG_E0

125

Developer Reference Guide

3.5.8.9.1

HRESULT GetOriginalValue([in] long iRow, [in] VARIANT

iCol, [out, retval] VARIANT *pVal)

HRESULT RowStatus([in] long iRow, [out, retval] enum

AtoRowStatus *pVal)

CancelUpdate Method
Cancels a pending update. This method may be called after Edit or AddNew to cancel the operation.

HRESULT CancelUpdate();

3.5.8.9.2

ColumnNumber Property
Returns a column number.

HRESULT ColumnNumber([in] VARIANT vColName, [out, retval] long *pCol);

Parameters
vColName:

Name of the column.

pCol:

Address of the column number to be retreived.

Return Values
S_OK.

Remarks
It is faster to read data from tables using the column number instead of the column name. It also works for linked fields.
For instance you can write in VBScript:

Set transmitters = doc.GetRecords("TRANSMITTERS", False)

colLatitude = transmitters.ColumnNumber("SITE_NAME.LATITUDE")
For i = 1 To transmitters.RowCount
latitude = transmitters.GetValue i, colLatitude
Next

3.5.8.9.3

CanEdit Property
Checks if rows can be modified.

HRESULT CanEdit([out, retval] VARIANT_BOOL *pVal);

Parameters
pVal:

Address of the property to be retrieved.

Return Values
S_OK.
VARIANT_FALSE, if the Edit operation on this table is undefined.

3.5.8.9.4

CanAddNew Property
Checks if rows can be added.

HRESULT CanAddNew([out, retval] VARIANT_BOOL *pVal);

Parameters
pVal:

Address of the property to be retrieved.

Return Values
S_OK.
VARIANT_FALSE, if the AddNew operation on this table is undefined.

3.5.8.9.5

CanFilterSort Property
Checks if rows can be filtered and sorted.

HRESULT CanFilterSort([out, retval] VARIANT_BOOL *pVal);

126

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Parameters
pVal:

Address of the property to be retrieved.

Return Values
S_OK.
VARIANT_FALSE, if Filter and Sort operations on this table are undefined.

3.5.8.9.6

Filter Property
Filters the table data according to a filter criteria. Refer to section 3.5.11.15 for the list of constants used to filter only modified, added, or deleted rows.

HRESULT Filter([in] VARIANT vCriteria);

Parameters
vCriteria:

Variant of type string or numeric type.

String: contains the filter string as displayed by Atoll in the "Table" property page available in the Atoll Explorer window.
Numeric: can be assigned one of the AtoRowFilter values.

Return Values
S_OK.

Remarks
If the table is retreived from Atoll with filtering on, setting this property is the same as setting the filter interactively in an
Atoll session. To remove any previous filter, call this method either with atoRowFilterNone value or with an empty string.
When the Atoll document is not connected to a database, atoRowFilterModifiedOrNew and atoRowFilterDeleted are not
available.

3.5.8.9.7

Filter Property
Returns the filter previously set on the table.

HRESULT Filter([out, retval] VARIANT *pvCriteria);

Parameters
pvCriteria:

Address of the filter to be retreived.

Return Values
S_OK.

3.5.8.9.8

Sort Property
Sort the table data.

HRESULT Sort([in] VARIANT vCriteria);

Parameters
vCriteria:
Variant of type string. Contains a list of comma separated database field names. Each
field is optionally followed by the DESC keyword to indicate that the sort order associated with the field is "Descending".

Return Values
S_OK.

Remarks
If the table is retreived from Atoll with filtering on, setting this property is the same as setting the sort order interactively in
an Atoll session. To remove any previous sort order, call this method with an empty string.

Example
Private Sub PrintTransmittersTable(transmRec, infoMsg)
For nRow = 1 To transmRec.RowCount
LogMessage infoMsg & ": " & transmRec.GetValue(nRow, "TX_ID")
Next

Forsk 2007

AT260_DRG_E0

127

Developer Reference Guide

End Sub
Sub Main
Set t = ActiveDocument.GetRecords("transmitters", False)
Sort ascending according to the "SITE_NAME" database field
t.Sort = "SITE_NAME"
PrintTransmitterTables t, "Sort = SITE_NAME"
Sort descending according to the "SITE_NAME" database field
t.Sort = "SITE_NAME DESC"
PrintTransmittersTable t, "Sort = SITE_NAME DESC"
end sub

3.5.8.9.9

Sort Property
Returns the sort order previously set on the table.

HRESULT Sort([out, retval] VARIANT *pvCriteria);

Parameters
pvCriteria:

Address of the sort order to be retreived.

Return Values
S_OK.

3.5.8.9.10

GetOriginalValue Property
Gets an original field value.

HRESULT GetOriginalValue([in] long iRow, [in] VARIANT iCol, [out, retval] VARIANT *pVal);
Parameters
iRow:

Row number.

iCol:

Column name or column number.

pVal:

Address of the value to be retreived.

Return Values
S_OK.

Remarks
If the row is unmodified, the original value is the same as the value itself.

3.5.8.9.11

RowStatus Property
Gets a row status. Refer to section 3.5.11.16 for the list of all possible row statuses.

HRESULT RowStatus([in] long iRow, [out, retval] enum AtoRowStatus *pVal);

Parameters
iRow:

Row number.

pVal:

Address of the status to be retreived.

Return Values
S_OK.

3.5.8.10

128

IPropertyContainer Interface
Object

Function

Property (P)
Method (M)

IDispatch

HRESULT Get([in] const BSTR bstrName, [out, retval] VARIANT *pValue);

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

HRESULT Set([in] const BSTR bstrName, [in] const VARIANT

varValue);

3.5.8.10.1

Get Property
Gets a property.

HRESULT Get([in] const BSTR bstrName, [out, retval] VARIANT *pValue);

Parameters
bstrName:

Property name.

pValue:

Address of the VARIANT where the property is retreived.

Return Values
S_OK, if the property was successfully retreived.
E_INVALIDARG, if the property is not present in this property container.

Remarks
Properties can be of the following data types:

3.5.8.10.2

VT_BOOL
VT_UI1 VT_I1
VT_UI2 VT_I2
VT_BSTR
VT_VARIANT
VT_UI4 VT_I4
VT_R4 VT_R8
An array of the previous data types, for instance VT_ARRAY | VT_BSTR

Set Property
Sets a property.

HRESULT Set([in] const BSTR bstrName, [in] const VARIANT varValue);

Parameters
bstrName:

Property name.

varValue:

Value of the property to set.

Return Values
S_OK, if the property was successfully set.

Remarks
Properties can be of the data types listed in .

3.5.8.11

IChildFolder Interface
Object
ChildFolder

Forsk 2007

Function

Property (P)
Method (M)

HRESULT _NewEnum(LPUNKNOWN* ppUnk)

HRESULT Application(IApplication**)

HRESULT CentreOnMap()

HRESULT Count(long*)

HRESULT Export(BSTR, IDispCoordSystem*, BSTR)

HRESULT Name(BSTR*)
HRESULT Name(BSTR)

HRESULT Item(VARIANT idx, IChildFolder**)

HRESULT Parent(VARIANT*)

HRESULT Redraw()

HRESULT Selected(VARIANT_BOOL*)
HRESULT Selected(VARIANT_BOOL)

AT260_DRG_E0

129

Developer Reference Guide

HRESULT Visible(VARIANT_BOOL*)
HRESULT Visible(VARIANT_BOOL)

The available properties of a ChildFolder object depend on the exact type of ChildFolder object returned by the ObjectKind
property.

3.5.8.11.1

Application Property
Read-only property that gets the Atoll application object.

HRESULT Application(IApplication**pVal);
Parameters
pVal:
Address of pointer variable that receives the application interface pointer. Upon
successful completion, *pVal contains the requested interface pointer of the object. If the object does not support the
IApplication interface, *pVal is set to NULL (see 3.5.8.1 IApplication interface).

Return Values
S_OK, if the interface is supported. Otherwise, E_NOINTERFACE.
E_POINTER, if pVal is NULL.

3.5.8.11.2

Parent Property
Read-only property that gets the object containing the calling object. In the case of a root child folder object, ti returns the
Document object. In the case of a child of any parent-child, it returns the parent-child.

HRESULT Parent(VARIANT* pVal);

Parameters
pVal:
Address of pointer variable that receives the parent interface pointer (see 3.5.8.3
IDocument and 3.5.8.11 IChildFolder interfaces).

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.11.3

Name Property
Property that gets or sets the item name.

HRESULT Name(BSTR *pVal);

HRESULT Name(BSTR newVal);
Parameters
pVal:

Address of string that receives the items name.

newVal:

String that contains the new name.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

Example
VBScript: (Renaming the Transmitters folder)

Dim folder
Dim dataTab
Dim folderName
Set dataTab = app.ActiveDocument.GetRootFolder(atoData)
For Each folder in dataTab
folderName = folder.Name
If folderName = Transmitters Then
Folder.Name = TransmittersTest

130

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

End if
Next

3.5.8.11.4

Count Property
Returns the number of sub-children of an item.

HRESULT Count(long *pVal);

Parameters
pVal:

Address of the long that receives the number of children.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.11.5

Item Property
Read-only property that gets one item from the children collection.

HRESULT Item(VARIANT idx, IChildFolder* *pVal);

Parameter
idx:
An integer or a string that identifies the returned child. If you specify a Long, the Item
method fetches the item by its zero-based index in the collection. If you specify a String, the childs name is used to find
the appropriate child.
pVal:
Address of the pointer variable that receives the child folder interface pointer. Upon
successful completion, *pVal contains the requested child pointer of the object. If no matching child is found, *pVal is set
to NULL.

Return Values
S_OK.
E_FAIL, if child is not found.
E_POINTER, if pVal is NULL.

3.5.8.11.6

_NewEnum Property
Specific property used to enumerate the objects of a collection.

HRESULT _NewEnum(LPUNKNOWN* ppUnk);

Parameters
ppUnk:

Address of pointer variable that receives the item interface pointer.

Return Values
S_OK.
E_POINTER, if ppUnk is NULL.

Remarks
With Visual C++, you can browse a collection to find a particular item using the _NewEnum property or the Item method.
In Visual Basic (or VBScript), it is not necessary to use the _NewEnum property, as it is automatically used in the implementation of For Each ... Next.

Example
VBScript:

Set modules = app.ActiveDocument.GetRootFolder(2)

For Each module In modules
do something with module
Next
C++:

Forsk 2007

AT260_DRG_E0

131

Developer Reference Guide

IChildFolderPtr pModules;
HRESULT hr = pDoc->GetRootFolder(atoModule, &pModules) ;
if (FAILED(hr)) return hr;
for (int i = 0; i < pModules->get_Count(); i++)
{
IChildFolderPtr pMod;
_variant_t idx = (short)i;
hr = pModules->get_Item(idx, &pMod);
if (FAILED(hr)) return hr;
// Do something with pMod
}

3.5.8.11.7

Visible Property
Property that gets or sets the visibility flag of an item.

HRESULT Visible(VARIANT_BOOL *pVal);

HRESULT Visible(VARIANT_BOOL newVal);
Parameters
pVal:
and VARIANT_FALSE otherwise.

Address of the pointer variable that receives VARIANT_TRUE, if the child is visible,

newVal:

VARIANT_TRUE or VARIANT_FALSE.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

Remarks
This property does not strictly apply to all types of items. However, it will be ignored if called for a child that does not support
it. No error will be returned.

Example
VBScript:

dataFolder.Item("Predictions").Visible = true

3.5.8.11.8

Selected Property
Property that gets or sets the selected flag of an item.

HRESULT Selected(VARIANT_BOOL *pVal);

HRESULT Selected(VARIANT_BOOL newVal);
Parameters
pVal:
or VARIANT_FALSE otherwise.

Address of the pointer variable that receives VARIANT_TRUE, if the child is selected,

newVal:

VARIANT_TRUE or VARIANT_FALSE.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

Remarks
This property does not strictly apply to all types of items. However, it will be ignored if called for a child that does not support
it. No error will be returned.

Example
VBScript:

132

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Public Sub SelectTx

Set doc = ActiveDocument
Set dataFolder = doc.GetRootFolder(0)
For Each folder In dataFolder
If folder.Name = "Transmitters" Then
folder.Item("Site0_0").Selected = True
End If
Next
End Sub

3.5.8.11.9

Export Method
Method that exports a child in a given format. This method can only be used for studies.

HRESULT Export(BSTR fileName, IDispCoordSystem* proj, BSTR resolution;format);

Parameter
FileName:

String containing the destination file name.

proj:

The projection to be used for the export.

resolution:
The export resolution for the prediction study being exported. If not provided, Atoll
displays a dialog box asking the user to define a resolution.
format:
String containing the file format to be used for the export. These strings are the same
keywords as those written in a configuration file. Read Atoll documentation to learn more about these formats (SHP, AGD,
MIF, BMP, TIF, TXT, and ASC, i.e. ArcView Grid ASCII format).

Return Values
S_OK.
E_POINTER, if proj is NULL.

Remarks
This property does not strictly apply to all types of items. However, it will be ignored if called for a child that does not support
it. No error will be returned.
This method exports the geographic coverage prediction study to the file specified when using SHP, AGD, MIF, BMP, and
TIF formats. However, if you specify TXT or ASC formats, this method will export the study report in a tabulated ASCII text
or ArcView Grid ASCII formats. This prediction study report is the same as the one available by right-clicking the study in
Atoll and selecting Generate Report.

Example
VBScript:

Public Sub ExportStudy

Set doc = ActiveDocument
Set data = doc.GetRootFolder(0)
Set child = data.Item("Prdictions")
Set study = child.Item("myStudy")
Set projection = doc.CoordSystemProjection
Export the study in BMP format
study.Export "c:\temp\myExport.bmp", projection, "BMP"
Export the study report in TXT format
study.Export "c:\temp\myExport.txt", projection, "BMP"
Export Study in ArcView Grid ASCII format
study.Export "c:\temp\myExport.asc", projection, "ARCVIEWGRIDASCII"
End Sub

3.5.8.11.10

CentreOnMap Method
Centres the map on this child.

HRESULT CentreOnMap();

Forsk 2007

AT260_DRG_E0

133

Developer Reference Guide

Return Values
S_OK.

Remarks
This property does not make sense for all types of items. No error will be thrown when called for items not supporting it.

3.5.8.11.11

Redraw Method
Redraws this child.

HRESULT Redraw();
Parameters
None.

Return Values
S_OK.

Remarks
This property does not make sense for all types of items. No error will be thrown when called for items not supporting it.

3.5.8.12

IChildFolder2 Interface
Object
ChildFolder

3.5.8.12.1

Function

Property (P)
Method (M)

HRESULT AddChild(VARIANT, long, IChildFolder2**)

HRESULT Remove()

HRESULT Position(long*)
HRESULT Position(long)

HRESULT Object(IUnknown** o)

HRESULT Dispatch(IDispatch** d)

HRESULT ObjectKind(BSTR* retVal)

AddChild Property
Adds a new child to the current child folder.

HRESULT AddChild(VARIANT spec, long position, IChildFolder2** pVal)

Parameters
spec:

Variant used to identify the child.

position:

Position where to add the new child.

pVal:

Pointer to the new child added.

Return Values
E_POINTER, if pVal is NULL.
S_OK, if adding was successful.
E_FAIL, if adding failed.

3.5.8.12.2

Remove Method
This method removes the current item from its parents list of children.

HRESULT Remove();
Parameters
None

Return Values
S_OK.
E_FAIL, if removal fails. This may happen because some folders cannot be removed, even in interactive mode, by design.

134

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

3.5.8.12.3

Position Property
Property that gets or sets the item position in the list of children.

HRESULT position(long

*pos);

HRESULT position(long newPos);

Parameters
pos:
Current position of the item in Atoll explorer, top is 0, bottom is Count() -1. (Count:
function of IChildFolder interface.)
newPos:

New position where to place the item.

if newPos 0, moves the item at the top of the list
if newPos GetCount()-1, moves the item at the bottom of the list

Return Values
S_OK.
E_POINTER, if pos is NULL.

3.5.8.12.4

Object Property
Access to some specific features on the child folder through some IUnknown interface.

HRESULT Object(IUnknown** o);

Parameters
o:

Adress of the pointer to the unknown object implementing the specific features.

Return Values
S_OK.
E_POINTER, if o is NULL.

Remarks
This function is to be used by add-ins and not macros as automation only support dispatch objects. See 3.5.8.12.5
Dispatch method.

3.5.8.12.5

Dispatch Property
Access to some specific features on the child folder through some IDispatch interface.

HRESULT dispatch(IDispatch** d);

Parameter
d:

Adress of the pointer to the dispatch object implementing the specific features.

Return Values
S_OK.
E_POINTER, if d is NULL.

Remarks
This function is to be used by macros as automation only support dispatch objects. It may also be used by add-ins.

3.5.8.12.6

ObjectKind Property
This method returns a character string representing in a unique manner the specific features implemented by the actual
object.

HRESULT ObjectKind(BSTR* retVal);

Parameters
retVal:

Address of the character string.

Return Values
S_OK.

Forsk 2007

AT260_DRG_E0

135

Developer Reference Guide

E_POINTER, if retVal is NULL.

Remarks
For add-ins or macros to be able to identify in a unique way character strings used to describe specific features, the API
needs to publish the correspondances.

Atoll
Release

SID

Character String Value

Specific Features

2.4.0

SID_CLUTTER

{7CB51DE8-A961-11D2-8688-0060086457D1}

Access to tabular
clutter properties.
See IClutter interface

2.4.0

SID_SIMULATIONS

{CDDF1E1D-1963-4D80-A057-D23A19570984}

Access to Simulations
folder

2.4.0

SID_SIMULATIONSGROUP

{AF5E2B98-1D54-48FA-89C5-8BFA2936ABF2}

Access to Groups of
simulations subfolder

2.4.0

SID_SIMULATION

{095C5D90-96F1-4BA8-85BB-B2F990AC2DD9}

Access to
Simulation items.
See ISimulation
interface

2.5.1

SID_SITES

{90443F68-5B3B-4AFD-B7BB-B057095EBAAD}

Access to Sites folder

2.5.1

SID_ANTENNAS

{5FBEB2AE-3BBB-4FBA-94D8-5D8EA5A32069}

Access to Antennas
folder

2.5.1

SID_TRANSMITTERS

{F7E891E8-F7F5-4870-BF63-AF559AD50FD3}

Access to
Transmitters folder

2.5.1

SID_PREDICTIONS

{DA676EF0-E300-4AFF-BBFA-EC55D3798E4F}

Access to Predictions
folder

2.5.1

SID_UMTS_PARAMETERS

{D4F57EE3-7785-4348-9BA6-28998AA6BD80}

Access to UMTS
Parameters folder

2.5.1

SID_CW_MEASUREMENTS

{41413C4A-C9DE-43DD-A917-612A0AF198FC}

Access to CW
Measurements folder

2.5.1

SID_MEASURE_TX

{2C102EE5-BFF4-4A5A-8130-02BD0E2F70D7}

Access to CW
Measurements
Transmitter

2.5.1

SID_MEASURE_ITEM

{36858A48-7A85-482E-9DA0-B9E935ADE84C}

Access to CW
Measurements

2.5.1

SID_TESTMOBILEDATA

{21C11380-D8CF-4902-B622-763522AD9FC4}

Access to Test Mobile

Data folder

2.5.1

SID_NUM_MEASURE_ITEM

{916801F9-0539-448C-8C0C-491FAC6399ED}

Access to Test Mobile

Data

2.5.1

SID_PARAMETERS_FOLDER

{43B8845-5226-454F-908F-59A500DB4FD1}

Access to Parameters
folder

2.5.1

SID_HEXAGON_SCHEMA

{B167D45E-A0BC-4DC6-B9D7-6F7B131CADF1}

Access to Hexagonal
Design folder

2.6.0

SID_TRAFFICFOLDER

{B3B25A07-A994-4e8d-BBD1-51556D6C4245}

Access to Traffic
folder

3.5.8.13

3.5.8.13.1

IChildFolder3 Interface
Object

Function

Property (P)
Method (M)

ChildFolder

HRESULT GetProperty([in] const BSTR bstrName, [out,

retval] VARIANT *pValue);

HRESULT SetProperty([in] const BSTR bstrName, [in]

const VARIANT varValue);

GetProperty Property
Gets a property from a property container.

HRESULT GetProperty([in] const BSTR bstrName, [out, retval] VARIANT *pValue);

Parameters
bstrName:

136

Property name.
AT260_DRG_E0

Forsk 2007

Chapter 3: General API

pValue:

Address of the VARIANT where the property is retreived.

Return Values
S_OK, if the property was successfully retreived.
E_INVALIDARG, if the property is not present in this property container.

Remarks
Properties can be of the following data types:

3.5.8.13.2

VT_BOOL
VT_UI1 VT_I1
VT_UI2 VT_I2
VT_BSTR
VT_VARIANT
VT_DISPATCH (can contain ITabularData data)
VT_UI4 VT_I4
VT_R4 VT_R8
An array of the previous data types, for instance VT_ARRAY | VT_BSTR

SetProperty Method
Sets a property in a property container.

HRESULT SetProperty([in] const BSTR bstrName, [in] const VARIANT varValue);

Parameters
bstrName:

Property name.

varValue:

Value of the property to set.

Return Values
S_OK, if the property was successfully set.

Remarks
Properties can be of the data types listed in .

3.5.8.14

IClutter Interface
Object
Clutter

Function

Property (P)
Method (M)

HRESULT Source(IDispatch ** pSource)

HRESULT ClassAttributes(ITabularData ** ppTable)

HRESULT DefaultAttributes(ITabularData ** ppTable)

IClutter inherits from IDispatch, thus it may be used directly by macros.

3.5.8.14.1

Source Property
Provides the original IChildFolder2 source back.

HRESULT Source(IDispatch ** pSource)

Parameters
pSource:

Pointer to the folder corresponding to the functionnality (Clutter Classes folder)

Return Values
E_POINTER, if pSource is NULL
S_OK.

3.5.8.14.2

ClassAttributes Property
This method gives access to all attributes of the clutter, attached with the clutter classes i.e. code, color, STD_DEV,
FORTHO, %INDOOR and so on.

HRESULT ClassAttributes(ITabularData ** ppTable);

Forsk 2007

AT260_DRG_E0

137

Developer Reference Guide

Parameters
ppTable:
Pointer to the attributes of Clutter properties presented in a Tabular-Data manner.
Corresponds to the content of the Description tab in Clutter properties.

Return Values
E_POINTER, if ppTable is NULL
S_OK.
E_FAIL, if reading these data fails.

Remark
In the specific case where the check box Use default values only, in the Default Values tab of the properties dialog of the
clutter, is checked, the tabular data contains these default values.

3.5.8.14.3

DefaultAttributes Property
This method gives access to default attributes of the Clutter.

HRESULT DefaultAttributes (ITabularData ** ppTable);

Parameters
ppTable:
Pointer to the default attributes of Clutter properties presented in a tabular data like
manner. Corresponds to the content of the Default Values tab in Clutter properties dialog.

Return Values
E_POINTER, if ppTable is NULL
S_OK.
E_FAIL, if reading these data fails.

Sample in a VBS macro

function ScanFolders
Set geo = ActiveDocument.GetRootFolder(1)
For each item In geo
MsgBox item.Name
MsgBox item.ObjectKind
if item.ObjectKind = "{7CB51DE8-A961-11D2-8688-0060086457D1}" then
MsgBox "Found"
Set clutter = item.dispatch
Set values =

clutter.ClassAttributes

MsgBox values.RowCount
MsgBox values.ColumnCount
For j = 0 To Values.RowCount
For i = 1 To Values.ColumnCount
colName = Values.GetValue(j, i)
MsgBox colName
Next
Next
end if
Next
end function

3.5.8.15

ISimulationsGroup Interface
Object
SimulationsGroup HRESULT

138

Function

Source(IDispatch ** pSource)

AT260_DRG_E0

Property (P)
Method (M)
P

Forsk 2007

Chapter 3: General API

HRESULT Statistics(ITabularData** ppTable)

HRESULT MeanSimulation(ISimulation** meanValues)

HRESULT
Values)

StdDevSimulation

(ISimulation**

stdDev-

ISimulationsGroup inherits from IDispatch, thus it may be used directly by macros.

3.5.8.15.1

Source Property
Provides the original IChildFolder2 source back.

HRESULT Source(IDispatch** source)

Parameters
pSource:
folder).

Pointer to the folder corresponding to the functionnality (here Simulation Groups

Return Values
E_POINTER, if pSource is NULL
S_OK.

3.5.8.15.2

Statistics Property
Provides global statistics about the results of the simulations group.

HRESULT Statistics(ITabularData** ppTable)

Currently not implemented.

Parameters
ppTable:

Pointer to the folder corresponding to the statistics table.

Return Values
E_POINTER, if ppTable is NULL
E_NOTIMPL.

3.5.8.15.3

MeanSimulation Property
Access to the mean simulation results. This corresponds to the data obtained when asking for mean simulation in simulation groups menu: Mean Simulation tab.

HRESULT MeanSimulation(ISimulation** meanValues);

Parameters
meanValues:
Pointer to the virtual mean simulation created to display mean values for the different
kind of results provided in the end of execution of simulations of the group.

Return Values
E_POINTER, if meanValues is NULL
S_OK

3.5.8.15.4

StdDevSimulation Property
Access to the standard deviation results of the mean simulation. This corresponds to the data obtained when asking for
mean simulation in simulation groups menu: Standard Deviation tab.

HRESULT StdDevSimulation (ISimulation ** stdDevValues);

Parameters
stdDevValues:
Pointer to the virtual standard deviation simulation created to display standard deviation values for the different kind of results provided in the end of execution of simulations of the group.

Return Values
E_POINTER, if stdDevValues is NULL
S_OK.

Forsk 2007

AT260_DRG_E0

139

Developer Reference Guide

3.5.8.15.5

Example
See section 3.5.8.8.18 for an example of the mehtods of the ISimulationGroups interface. This example shows how to read
the results from the Simulations folder using a VBS macro.

3.5.8.16

ISimulation Interface
ISimulation inherits from IDispatch, thus it may be used directly by macros.
It gives access to all the simulation results.

Object
Simulation

3.5.8.16.1

Function

Property (P)
Method (M)

HRESULT Source(IDispatch ** pSource)

HRESULT Statistics(ITabularData** ppTable)

HRESULT Cells(ITabularData ** pResults)

HRESULT Sites(ITabularData ** pResults)

HRESULTS Mobiles(ITabularData ** pResults)

Source Property
Provides the original IChildFolder2 source back.

HRESULT Source(IDispatch** source)

Parameters
pSource:

Pointer to the folder corresponding to the functionnality (here Simulation folders).

Return Values
E_POINTER, if pSource is NULL
S_OK.

3.5.8.16.2

Statistics Property
Provides global statistics about the results of the simulation.
Currently not implemented.

HRESULT Statistics(ITabularData** ppTable)

Parameters
ppTable:

Pointer to the folder corresponding to the statistics table.

Return Values
E_POINTER, if ppTable is NULL
E_NOTIMPL.

3.5.8.16.3

Cells Property
Provides the results of the simulation as presented in Cells tab of the Property page.

HRESULT Cells(ITabularData** pResults);

Parameters
pResults:
erty Page.

Pointer to the table of results corresponding to the Cells tab of the Simulations Prop-

Return Values
E_POINTER, if pResults is NULL
S_OK

3.5.8.16.4

Sites Property
Provides the results of the simulation as presented in Sites tab of the Property page.

HRESULT Sites(ITabularData** pResults);

140

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Parameters
pResults:
erty Page.

Pointer to the table of results corresponding to the Cells tab of the Simulations Prop-

Return Values
E_POINTER, if pResults is NULL
S_OK

3.5.8.16.5

Mobiles Property
Provides the results of the simulation as presented in Sites tab of the Property page.

HRESULT Sites(ITabularData** pResults);

Parameters
pResults:
tions Property Page.

Pointer to the table of results corresponding to the Cells tab of the Simula-

Return Values
E_POINTER, if pResults is NULL
S_OK.

3.5.8.16.6

Example
See section 3.5.8.8.18 for an example of the mehtods of the ISimulationGroups interface. This example shows how to read
the results from the Simulations folder using a VBS macro.

3.5.8.17

IDispCoordSystem Interface
To change any property of a coordinate system, please refer to the Technical Reference Guide.

Object
CoordSystem

3.5.8.17.1

IDispCoordSystem functions

Property (P)
Method (M)

HRESULT Code(long *pVal)

HRESULT Code(long val)

HRESULT ConvertCoordsTo(IDispCoordSystem *targetCS,

VARIANT inPoints, VARIANT *outPoints)

HRESULT Datum(long *pVal)

HRESULT Datum(long val)

HRESULT DatumName(BSTR *pVal)

HRESULT Description(BSTR *pVal)

HRESULT Ellipsoid(long* pVal)

HRESULT Ellipsoid(long pVal)

HRESULT EllipsoidName(BSTR* pVal)

HRESULT Name(BSTR *pVal)

HRESULT Name(BSTR pVal)

HRESULT Pick(OLE_HANDLE parentWindow, WORD types,

VARIANT_BOOL *ret)

HRESULT ProjMethod(ProjectionMethod *pVal)

HRESULT ProjParameter(ProjParameterIndices index, double

*pVal)

HRESULT SetDatum(long ellipsoidCode, VARIANT params)

HRESULT SetProjection(ProjectionMethod met, VARIANT

projectionParameters)

HRESULT Unit(GeographicUnit *pVal)

HRESULT Unit(GeographicUnit newVal)

Code Property
Property that gets or sets the numeric code of the coordinates system.

HRESULT Code(long *pVal);

Forsk 2007

AT260_DRG_E0

141

Developer Reference Guide

HRESULT Code(long val);

Parameters
pVal:

Address of the Long read as the code of the system.

val:

Long value representing the code of the system to set.

Return Values
S_OK.
E_POINTER, if pVal is NULL.
E_INVALIDARG, if val does not correspond to a system code recognized by Atoll.
Notes:

3.5.8.17.2

Classical system codes have values less than 32767. System codes greater or equal to 32768 correspond
to user defined systems.

ConvertCoordsTo Method
Converts the coordinates of a point expressed in the current system to another one.

HRESULT ConvertCoordsTo(IDispCoordSystem *targetCS, VARIANT inPoint, VARIANT

*outPoint);
Parameters
targetCS:

Pointer of the coordinates system to which input coordinates must be converted.

InPoints:
VT_R8: x and y.

Coordinates of the input point to convert expressed in the current system. Array of 2

OutPoints:
x and y.

Coordinates of the output converted point expressed in targetCS. Array of 2 VT_R8:

Return Values
S_OK.
E_POINTER, if targetCS is NULL or outPoint is NULL.
E_INVALIDARG, if there is a problem with the converter.
Other output values may be obtained according to the type of error detected (incorrect inputs, problems with some parameters in the conversion, etc).

Example
C++:

//Reading and preparing the coordinates of the first SITE in the TABLE, if any
long nRow=0;
_variant_t latiVal,longiVal;
_variant_t latiCol, longiCol;
latiCol.vt

= VT_BSTR;

longiCol.vt

= VT_BSTR;

latiCol.bstrVal = ::SysAllocString(CComBSTR(_T("LATITUDE")));
longiCol.bstrVal = ::SysAllocString(CComBSTR(_T("LONGITUDE")));
long nSites = 0;
pSites->get_RowCount(&nSites);
// Assumption: nSites >=1
pSites->GetValue(1, latiCol, &latiVal);
pSites->GetValue(1, longiCol, &longiVal);
CComBSTR latiStr, longiStr;
pSites->GetFormattedValue(1, latiCol, &latiStr);
pSites->GetFormattedValue(1, longiCol, &longiStr);
double lati=0, longi=0;
latiVal.ChangeType(VT_R8); lati = latiVal.dblVal;
longiVal.ChangeType(VT_R8); longi = longiVal.dblVal;

142

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

// Constructing input parameter

VARIANT inputPt;
COleSafeArray array;
array.CreateOneDim(VT_VARIANT, 2);
long idx[2]; idx[0]=0; idx[1] = 1;
VARIANT vv; vv.vt

= VT_R8;

vv.dblVal = longi.dblVal;
array.PutElement(&idx[0], &vv);
vv.dblVal = lati.dblVal;
array.PutElement(&idx[1], &vv);
VARIANT v

array.Detach();

inputPt.vt

v.vt;

inputPt.parray

v.parray;

v.vt

VT_EMPTY;

// Reading document's systems

CComPtr<IDispCoordSystem> internalSystem;
CComPtr<IDispCoordSystem> projectionSystem;
pDoc->get_CoordSystemInternal(&internalSystem);
pDoc->get_CoordSystemProjection(&projectionSystem);
// Conversion
_variant_t
putPt);

outputPt = internalSystem->ConvertCoordsTo(projectionSystem, in-

// Transform output to double

double x = 0., y = 0.;
COleSafeArray sa;sa.Attach(outputPt);
long idx[2]; idx[0]=0; idx[1] = 1;
_variant_t val;sa.GetElement(&idx[0], &val);
VariantChangeType(&val, &val, 0, VT_R8);
x = val.dblVal;
sa.GetElement(&idx[1], &val);
VariantChangeType(&val, &val, 0, VT_R8);
y = val.dblVal;
VBScript:

Public Sub TestConvertCoords()

Set doc = ActiveDocument
Set sites = doc.GetRecords("Sites", true)
Set internalSystem

= doc.CoordSystemInternal

Set projectionSystem = doc.CoordSystemProjection

Dim ptsInput(2)
ptsInput(1) = sites.GetValue(1, "LATITUDE")
ptsInput(0) = sites.GetValue(1, "LONGITUDE")
ptsOutput

= internalSystem.ConvertCoordsTo(projectionSystem, ptsInput)

MsgBox "x = " + CStr(ptsOutput (0)) + ", y = " + CStr(ptsOutput (1))

End Sub
Additional Features: ICoordSystem
There is another possibility to convert point coordinates in a more friendly way, using a hidden interface named ICoordSystem:

HRESULT InPlaceConvert([in] ICoordSystem *targetCS, [in] long nPoints, [in,

out, size_is(nPoints)] GEOPOINT *points);

Forsk 2007

AT260_DRG_E0

143

Developer Reference Guide

To use this function available on ICoordSystem interface, you must get this interface from the object implementing the
IDispCoordSystem interface, using QueryInterface method.

CComPtr<IDispCoordSystem> internalSystem;
CComPtr<IDispCoordSystem> projectionSystem;
pDoc->get_CoordSystemInternal(&internalSystem);
pDoc->get_CoordSystemProjection(&projectionSystem);
CComPtr<ICoordSystem> hiddenInternalSystem;
CComPtr<ICoordSystem> hiddenProjectionSystem;
internalSystem->QueryInterface(__uuidof(ICoordSystem),(void**)&hiddenInternalSystem);
projectionSystem->QueryInterface(__uuidof(ICoordSystem),(void**)&hiddenProjectionSystem);
GEOPOINT points[5];
GetPoints(points); // Whatever function filling the array with 5 points whose
// coordinates follow internal system.
hiddenInternalSystem->InPlaceConvert(hiddenProjectionSystem, 5 , points);
The only restriction to this function is that it cannot be used in a macro context (VBS, VBScript, ) and so it must be used
carefully.
Other methods are available on the ICoordSystem interface, but they are much less useful than InPlaceConvert and wont
be detailed more than the following in this documentation.

HRESULT Init([in] LPCSPARAMS params);

// Init of a new CoordSystem

HRESULT GetParams([out] LPCSPARAMS params);

ordSystems parameters

// Detailed description of Co-

HRESULT Clone([out, retval] ICoordSystem **ppCS); // Duplicates the CoordSystem

3.5.8.17.3

Datum Property
Property that gets or sets the numeric value of the datum.

HRESULT Datum(long *pVal);

HRESULT Datum(long val);
Parameters
pVal:

Address read as the datum code of the system.

val:

Value to be set as the datum code of the system.

Return Values
S_OK.
E_POINTER, if pVAl is NULL.
E_INVALIDARG, if val does not correspond to a datum code recognized by Atoll.

3.5.8.17.4

DatumName Property
Name of the datum.

HRESULT DatumName(BSTR *pVal);

Parameters
pVAl:

Pointer of the datum name.

Return Values
S_OK.
E_POINTER, if pVAl is NULL.

3.5.8.17.5

Description Property
Description of the datum.

HRESULT Description(BSTR *pVal);

144

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Parameters
pVAl:

Pointer of datum description.

Return Values
S_OK.
E_POINTER, if pVAl is NULL.

3.5.8.17.6

Ellipsoid Property
Property that gets or sets the numeric value of the ellipsoid.

HRESULT Ellipsoid(long* pVal);

HRESULT Ellipsoid(long Val);
Parameters
pVal:

Address read as the ellipsoid code of the system.

val:

Value to be set as the ellipsoid code of the system.

Return Values
S_OK.
E_POINTER, if pVal is NULL.
E_INVALIDARG, if val does not correspond to an ellipsoid code recognized by Atoll.

3.5.8.17.7

EllipsoidName Property
Name of the ellipsoid.

HRESULT EllipsoidName(BSTR* pVal);

Parameters
pVal:

Pointer to the name of the ellipsoid.

Return Values
S_OK.
E_POINTER, if pVal is NULL.

3.5.8.17.8

Name Property
Property that gets or sets the name of the coordinates system.

HRESULT Name(BSTR *pVal);

HRESULT Name(BSTR pVal); [id(8)]
Parameters
pVal:

Address read as the name of the coordinates system.

val:

Value to be set as the name of the coordinates system.

Return Values
S_OK.
E_POINTER, if pVAl is NULL.

3.5.8.17.9

Pick Method
Opens the coordinates system dialog.

HRESULT Pick(OLE_HANDLE parentWindow, WORD types, VARIANT_BOOL *ret);

Parameters
parentWindow:

OLE_HANDLE of the parent window for which the dialog is required to be opened.

types:
Bitset of CoordSysType (see CoordSysTypes) corresponding to the types of systems
the dialog must filter before opening.
ret:
OK, otherwise VARIANT_FALSE.

Forsk 2007

Pointer to a VARIANT_BOOL, set to VARIANT_TRUE if the user quits the dialog with

AT260_DRG_E0

145

Developer Reference Guide

Return Values
S_OK.
E_POINTER, if ret is NULL.

CoordSysTypes
enum CoordSysType
{ fgUndefinedCoordSys = 1,
fgGeographic2D

= 2,

fgProjected2D

= 4

} CoordSysType;

3.5.8.17.10

ProjMethod Property
Projection method used for the current coordinates system.

HRESULT ProjMethod(ProjectionMethod *pVal);

Parameters
pVal:

Pointer to the read ProjectionMethod (see ProjectionMethods).

Return Values
S_OK.
E_POINTER, if pVal is NULL.

ProjectionMethods
enum ProjectionMethod
{
fgUndefinedProjection

= 0,

fgNoProjection

= 1,

fgLambertConfConic1SP

= 2,

fgLambertConfConic2SP

= 3,

fgMercator

= 4,

fgCassiniSoldner

= 5,

fgTransverseMercator

= 6,

fgTransvMercatorSouthOriented= 7,
fgObliqueStereographic

= 8,

fgNewZealandMapGrid

= 9,

fgHotineObliqueMercator

= 10,

fgLabordeObliqueMercator

= 11,

fgSwissObliqueCylindrical

= 12,

fgObliqueMercator

= 13,

fgUTMProjection

= 14

} ProjectionMethod;

3.5.8.17.11

ProjParameter Property
Reads a parameter of the projection.

HRESULT ProjParameter(ProjParameterIndices index, double *pVal);

Parameters
index:

Index of the parameter to read.

pVal:

Address of the double containing the value of the parameter.

Return Values
S_OK.

146

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

E_POINTER, if pVal is NULL.
E_INVALIDARG, if index is out of the ProjParameterIndices range (see ProjParameterIndices).
Keep in mind that the real valid range of index parameters depends on the projection method.

ProjParameterIndices
enum ProjParameterIndices
{
fgUTMZoneNumber

= 0,

fgLongitudeOfOrigin

= 0,

fgLatitudeOfOrigin

= 1,

fgFalseEasting

= 2,

fgFalseNorthing

= 3,

fgScaleFactorAtOrigin

= 4,

fgLatitudeOf1stParallel

= 4,

fgAzimuthOfCentralLine

= 5,

fgLatitudeOf2ndParallel

= 5,

fgAngleFromRectfifiedToSkewedGrid = 6
} ProjParameterIndices;

3.5.8.17.12

SetDatum Method
Changes the datum of the system.

HRESULT SetDatum(long ellipsoidCode, VARIANT params);

Parameters
ellipsoidCode:

Numeric code of the ellipsoid of the new datum.

params:

Parameters of the projection provided as an array of variants.

Return Values
S_OK.
E_INVALIDARG, if the datum is incorrect.
Other errors, if a parameter in the array of variants has incorrect value.

3.5.8.17.13

SetProjection Method
Changes the projection of the system.

HRESULT SetProjection(ProjectionMethod method, VARIANT projectionParameters);

Parameters
method:

New projection method (see ProjectionMethods).

projectionParameters:
on the method.

Parameters of the new projection provided as an array of variants. The size depends

Return Values
S_OK.
E_INVALIDARG, if the method is incorrect.
Other errors, if a parameter in the array of variants has incorrect value.

3.5.8.17.14

Unit Property
Property that gets or sets the unit of the coordinate system.

HRESULT Unit(GeographicUnit *pVal);

HRESULT Unit(GeographicUnit newVal);
Parameters
pVAl:

Forsk 2007

Address of the current geographic unit (see GeographicUnits) of the system.

AT260_DRG_E0

147

Developer Reference Guide

newVal:

New value for the geographic unit.

Return Values
S_OK.
E_POINTER, if pVal is NULL.
E_INVALIDARG, if the unit is incorrect.

GeographicUnits
enum GeographicUnit
{

fgUnspecifiedUnit = -1,
fgMeter

= 0,

fgKilometer

= 1,

fgFoot

= 2,

fgLink

= 3,

fgChain

= 4,

fgYard

= 5,

fgNauticalMile

= 6,

fgMile

= 7,

fgRadian

= 100,

fgDegree

= 101,

fgGrad

= 102,

fgArcMinute

= 103,

fgArcSecond

= 104

} GeographicUnit;

3.5.8.18

IApplicationKeyRef Interface
This interface is implemented by an add-in in order to get the reference of the dongle (fixed or floating) on which the current
Atoll session is running.

Object
ApplicationKeyRef

HRESULT IsFixedKey()

HRESULT IsNetworkKey()

HRESULT GetFskKeyRef([in]
BSTR* reference)

3.5.8.18.1

Property (P)
Method (M)

IApplicationKeyRef functions

ULONG

keyType,

[out]

IsFixedKey Method
Method that returns true if the dongle being used for the current Atoll session is a fixed dongle.

HRESULT IsFixedKey();
Parameters
None

Return Values
S_OK for fixed license.
S_FALSE, otherwise.

3.5.8.18.2

IsNetworkKey Method
Method that returns true if the dongle being used for the current Atoll session is a floating license dongle.

HRESULT IsNetworkKey();
Parameters
None

148

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Return Values
S_OK for floating license.
S_FALSE, otherwise.

3.5.8.18.3

GetFskKeyRef Method
Method that returns the Forsks reference of the fixed or floating license dongle being used for the current Atoll session.

HRESULT GetFskKeyRef([in] ULONG keyType, [out] BSTR* reference);

Parameters
keyType:

0 for fixed license dongle. 1 for floating license dongle.

reference:

Character string representing the Forsks reference of the dongle.

Return Values
E_POINTER if the dongle reference is NULL.
S_OK if the dongle is of the type input in keyTpye.
S_FALSE if the dongle is not of the type input in keyType, and also if keyType is neither 0 nor 1.

3.5.8.18.4

Example
CComPtr<IServiceProvider> pSrv;
GetSite(IID_IServiceProvider,(void**)&pSrv);
IApplicationKeyRefPtr pKeyRef;
HRESULT
hr=pSrv->QueryService(SID_KEY_REF,__uuidof(IApplication
KeyRef),(void**)&pKeyRef);
CComBSTR str("You do not have a fixed key plugged.No ref available");
CComBSTR f=str;
if (hr==S_OK)
{
f=CComBSTR("Reference of fixed key

:");

hr=pKeyRef->IsFixedKey();
if (hr==S_OK)
hr=pKeyRef->GetFskKeyRef(0,&str);
else
{
f=CComBSTR("Reference of floating key :");
hr=pKeyRef->GetFskKeyRef(1,&str);
}
f.Append(str);
}
else
str=CComBSTR("Impossible to find the reference of the key.");

3.5.8.19

ITraffic Interface
Provides access to traffic map features.
Notes:

Forsk 2007

This interface is obtained through the Object or Dispatch property of the Atoll explorer item whose
ObjectKind property is the ITraffic interface identifier, formatted as a string.

Object

ITraffic functions

Property (P)
Method (M)

Traffic

HRESULT Source ([out, retval] IDispatch ** source)

HRESULT ScenarioProvider ([out, retval] ITrafficScenarioProvider ** ppProvider)

AT260_DRG_E0

149

Developer Reference Guide

3.5.8.19.1

Source Property
Gets the IDispatch interface of the explorer item implementing the ITraffic interface.

HRESULT Source ([out, retval] IDispatch ** source)

Parameters
source:

Address of an IDispatch pointer.

Return Values
S_OK if the source was successfully retrieved.
E_POINTER if the source pointer is NULL.
E_NOINTERFACE if the source could not be retrieved.

3.5.8.19.2

ScenarioProvider Property
Gets the scenario provider.

HRESULT ScenarioProvider ([out, retval] ITrafficScenarioProvider ** ppProvider)

Parameters
ppProvider:

Address of an ITrafficScenarioProvider pointer.

Return Values
S_OK if the provider was successfully retrieved.
E_POINTER if the ppProvider pointer is NULL.
E_NOTIMPL if there is no provider available.
E_FAIL if the provider could not be retrieved.
Notes:

3.5.8.19.3

The scenario provider is only available for UMTS documents.

Example
ITrafficPtr GetTrafficFolder(IDocument *pDocument)
{
USES_CONVERSION;
HRESULT hr;
ITrafficPtr pTraffic;
try
{
IChildFolder2Ptr pRoot = pDocument->GetRootFolder(atoGeo);
long count = 0;
hr = pRoot->get_Count(&count);
if (FAILED(hr))
throw hr;
for (long i = 0; i < count; ++i)
{
IChildFolderPtr pItemT;
hr = pRoot->get_Item(_variant_t(i), &pItemT);
if (FAILED(hr))
continue;
CComBSTR itemKind;
IChildFolder2Ptr pItem = pItemT;
hr = pItem->get_ObjectKind(&itemKind);
if (FAILED(hr))
continue;
if (itemKind == __uuidof(ITraffic))

150

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

{
// Found the traffic folder
IUnknownPtr pObject;
hr = pItem->get_Object(&pObject);
pTraffic = pObject;
break;
}
}
}
catch (...)
{
}
return pTraffic;
}

3.5.8.20

ITrafficScenarioProvider Interface
The traffic scenario provider allows third parties to build their own UMTS simulation module on top of Atoll core architecture. Raw mobiles data is generated according to a probability law and a set of traffic maps.

3.5.8.20.1

Object

ITrafficScenarioProvider functions

Property (P)
Method (M)

TrafficScenarioProvider

HRESULT GetMeanSize ([in] VARIANT selectedMapsNames,[in]

double
scale,[in]
VARIANT
reserved,[out, retval] ULONG *mobilesCount)

HRESULT
Create
([in]
VARIANT
selectedMapsNames,[in] double scale,[in] AtoTrafficScenarioLaw law,[in] VARIANT reserved,[out, retval]
ITabularData **mobiles)

GetMeanSize Property
Provides the mean count of mobiles.

HRESULT GetMeanSize ([in] VARIANT selectedMapsNames, [in] double scale, [in]

VARIANT reserved, [out, retval] ULONG * mobilesCount)
Parameters
selectedMapsNames:
Variant of type VT_ARRAY|VT_UI1. It contains the names of traffic environment map
names, coded as ASCII strings and separated by the NUL character.
scale:

Scaling factor used in the determination of the mobile count.

reserved:

Reserved for future use. Must be VT_EMPTY.

mobilesCount:

Address of the mobile count to be retrieved.

Return Values
S_OK if the mobile count was successfully retrieved.

3.5.8.20.2

Create Property
Creates raw mobiles data. The mobiles data is returned as a table containing the position of the mobiles and other information related to the state of mobiles.

HRESULT Create ([in] VARIANT selectedMapsNames, [in] double scale, [in]

AtoTrafficScenarioLaw law, [in] VARIANT reserved, [out, retval] ITabularData **
mobiles)
Parameters
selectedMapsNames:
Variant of type VT_ARRAY|VT_UI1. It contains the names of traffic environment map
names, coded as ASCII strings and separated by the NUL character.
scale:

Forsk 2007

Scale factor used in the determination of the mobiles count.

AT260_DRG_E0

151

Developer Reference Guide

law:
mobiles count.

Probability law used to get a random count of mobiles, given the mean size of the

reserved:

Reserved for future use. Must be VT_EMPTY.

mobiles:

Contains the mobiles data.

Column Name

Description

Type

Values

X coordinate

Long

Projection coordinate system of the document

Y coordinate

Long

Projection coordinate system of the document

SERVICE

Service name

String

From the UMTSServices table

TERMINAL

Terminal name

String

From the UMTSTerminals table

MOBILITY

Mobility type

String

From the UMTSMobility table

CLUTTER

Clutter code

Short

From the IClutter interface

ACTIVITY

Mobile activity

String

Active DL, UL, UL+DL

Return Values
S_OK if the mobiles data was successfully retrieved.

3.5.8.21

ITrafficPerEnvironment Interface
Provides access to traffic per environment information through API interface. Traffic data under the Traffic folder correspond to traffic in various formats, i.e. raster, vector and live traffic. Therefore, this interface goes through all the traffic
data in the Traffic folder to get info from environment based traffic only.

Object
Traffic

Function

Property (P)
Method (M)

HRESULT Source([out,retval] IDispatch ** pSource);

HRESULT ClassAttributes([out, retval] ITabularData

** ppTable);

HRESULT DefaultAttributes([out, retval] ITabularData

** ppTable);

ITrafficPerEnvironment inherits from IDispatch, thus it may be used directly by macros.

3.5.8.21.1

Source Property
Provides the original IChildFolder2 source back.

HRESULT Source([out,retval] IDispatch ** pSource);

Parameters
pSource:

Pointer to the folder corresponding to the functionnality (Traffic folder)

Return Values
E_POINTER, if pSource is NULL
S_OK.

3.5.8.21.2

ClassAttributes Property
This method gives access to all attributes of the traffic based on environment classes.

HRESULT ClassAttributes([out, retval] ITabularData ** ppTable);

Parameters
ppTable:
Pointer to the attributes of Traffic properties presented in a tabular data manner.
Corresponds to the content of the Description tab in properties of the traffic based on environments.

Return Values
E_POINTER, if ppTable is NULL
S_OK.
E_FAIL, if reading these data fails.

3.5.8.21.3

DefaultAttributes Property
This method gives access to default attributes of the Traffic.

152

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

HRESULT DefaultAttributes([out, retval] ITabularData ** ppTable);

Parameters
ppTable:
Pointer to the default attributes of Traffic properties presented in a tabular data
manner. Currently no default attributes exist.

Return Values
E_POINTER, if ppTable is NULL
S_OK.
E_FAIL, if reading these data fails.

Samples in a VBS macro

function ScanGeoTrafficAttrs
Set geo = ActiveDocument.GetRootFolder(1)
For each item In geo
MsgBox item.Name
MsgBox item.ObjectKind
if item.ObjectKind = "{B3B25A07-A994-4E8D-BBD1-51556D6C4245}" then
MsgBox "Found traffic"
MsgBox "Count"
MsgBox item.Count
For each child In item
MsgBox child.Name
MsgBox child.ObjectKind
Set traffic = child.dispatch
Set values =

traffic.ClassAttributes

MsgBox values.RowCount
MsgBox values.ColumnCount
For j = 0 To Values.RowCount
For i = 1 To Values.ColumnCount
colName = Values.GetValue(j, i)
MsgBox colName
Next
Next
Next
end if
Next
end function
sub main
Set data = ActiveDocument.GetRootFolder(0)
ScanFolders data
end sub
sub scanValues (values)
MsgBox values.RowCount
MsgBox values.ColumnCount
maxLine=values.RowCount
if values.RowCount > 2 then
maxLine=6
end if

Forsk 2007

AT260_DRG_E0

153

Developer Reference Guide

maxCol=values.ColumnCount
if values.ColumnCount>5 then
maxCol=5
end if
For j = 0 To maxLine
For i = 89 To 89+maxCol
colName = values.GetValue(j, i)
If IsNull(colName) Then
MsgBox "vide"
else
MsgBox colName
end if
Next
Next
end sub
function ScanFolders (it)
For each item In it
If item.ObjectKind = "{CDDF1E1D-1963-4D80-A057-D23A19570984}" then
MsgBox "Simulations found"
ScanFolders item
end if
if item.ObjectKind = "{AF5E2B98-1D54-48FA-89C5-8BFA2936ABF2}" then
MsgBox "Simulation group found"
set groupsimud= item.dispatch
set mean=groupsimud.MeanSimulation
set meancells=mean.cells
scanvalues meancells
set meansites=mean.sites
scanvalues meansites
set meanmobiles=mean.mobiles
scanvalues meanmobiles
set std=groupsimud.StdDevSimulation
set stdcells=std.cells
scanvalues stdcells
set stdsites=std.sites
scanvalues stdsites
set stdmobiles=std.mobiles
scanvalues stdmobiles
ScanFolders item
end if
if item.ObjectKind = "{095C5D90-96F1-4BA8-85BB-B2F990AC2DD9}" then
MsgBox "Simulation Found"
set simud = item.dispatch
set cells = simud.Cells
scanvalues cells
set sites = simud.Sites
scanvalues sites
set mobiles = simud.mobiles
scanvalues mobiles

154

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

end if
Next
end function

3.5.9

Outgoing Interfaces

3.5.9.1

_IApplicationEvents Interface
All events are managed through the connection point mechanism provided by ATL. Atoll keeps a container of all connection points, which have been declared with AtlAdvise. When something occurs, Atoll loops through its connection point
container and informs each connection point of what occured. The connection point implements the outgoing interface
defined by the server (Atoll) for a given set of events (i.e. the application Event interface) on the client-side (= in the add-in).
The events related to the application are fired:

Before the application shuts down

When a document has just been opened
Before a document is closed
Before a document is saved
When a document has been saved
When a new document has just been created
Before a document is refreshed from database
When a document has been refreshed from database
Before a document is archived in database
When a document has been archived in database
When a calculation is requested
After a calculation has completed

The method used within the wizard to implement connection points is based on the template class IDispEvenImpl. An
IDispEventImpl COM object handles all events mapped with an event sink map. Each event is identified by an id, whose
value matches the order of its declaration in the interface5.
Notes:

The method used to advise the server is DispEventAdvise, which in turn calls AtlAdvise.

We recommend you to copy the code generated by the wizard (see 3.2.3 Step 3: Catching Events) when you want to implement connection points.
This section describes each default method created by the wizard and explains when it is called by Atoll.

IApplicationEvents outgoing interface

HRESULT ArchiveDocumentComplete(IDocument* document)
HRESULT DocumentNewComplete(IDocument* document)
HRESULT DocumentOpenComplete(IDocument* document)
HRESULT DocumentSaveComplete (IDocument* document)
HRESULT RefreshDocumentComplete(IDocument* document)
HRESULT RunComplete(IDocument* document, VARIANT_BOOL all)
HRESULT WillArchiveDocument(IDocument* document, VARIANT_BOOL* evtStatus)
HRESULT WillCloseDocument(IDocument* document, VARIANT_BOOL* evtStatus)
HRESULT WillQuitApp(VARIANT_BOOL* evtStatus)
HRESULT WillRefreshDocument(IDocument* document, VARIANT_BOOL* evtStatus)
HRESULT WillRun(Idocument* document,VARIANT_BOOL all, VARIANT_BOOL* evtStatus);
HRESULT WillSaveDocument(IDocument* document, VARIANT_BOOL* evtStatus);
HRESULT LicenceAcquireComplete([in, unique] IDocument *pDocument,[in] long
lModuleID);
HRESULT LicenceReleaseComplete([in, unique] IDocument *pDocument, [in] long
lModuleID);

5.
There is a known bug in ATL and sometimes when compiling an add-in youll obtain strange messages about
ambiguity between ATL and a namespace. To troubleshoot it just enclose your declaration of atlbase.h with the following
piece of code :

#define ATL ATLFIX

#include <atlbase.h>
#undef ATL
namespace ATL = ::ATLFIX;

Forsk 2007

AT260_DRG_E0

155

Developer Reference Guide

3.5.9.1.1

WillQuitApp Method
Event fired when the user wants to exit an Atoll session. It occurs just before all add-ins are disconnected and after all
documents have been closed.

HRESULT WillQuitApp(VARIANT_BOOL* evtStatus);

Parameters
evtStatus:

Boolean set by the add-in to VARIANT_TRUE if Quit can continue or not.

Return Values
S_OK.

3.5.9.1.2

DocumentOpenComplete Method
Event fired when a document has been opened.

HRESULT DocumentOpenComplete(IDocument* document);

Parameters
document:

Document interface pointer to the document object which has been opened.

Return Values
S_OK.

3.5.9.1.3

WillCloseDocument Method
Event fired when the user wants to close a document. It occurs just before the document closes, i.e. after all confirmations
requested by Atoll have been answered (stop running tasks, save changes, etc).

HRESULT WillCloseDocument(IDocument* document, VARIANT_BOOL* evtStatus);

Parameters
document:

Document interface pointer of the document object being closed.

evtStatus:

Boolean set by the add-in telling Atoll if Close can continue or not.

Return Values
S_OK.

3.5.9.1.4

WillSaveDocument Method
Event fired when the user wants to save a document. It occurs just before the document file is saved but after a valid file
name is set.

HRESULT WillSaveDocument(IDocument* document, VARIANT_BOOL* evtStatus);

Parameters
document:

Document interface pointer of the document object being saved.

evtStatus:

Boolean set by the add-in tellin Atoll if Save can continue or not.

Return Values
S_OK.

3.5.9.1.5

DocumentSaveComplete Method
Event fired just after a document has been saved.

HRESULT DocumentSaveComplete (IDocument* document);

Parameters
document:
saved.

Document interface pointer of the document object which has been successfully

Return Values
S_OK.

156

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

3.5.9.1.6

DocumentNewComplete Method
Event fired when a new document has been created.

HRESULT DocumentNewComplete(IDocument* document);

Parameters
document:
created.

Document interface pointer of the document object that has been successfully

Return Values
S_OK.

3.5.9.1.7

WillRefreshDocument Method
Event fired when the user wants to refresh a document from database. It occurs just before the connection with the database is checked.

HRESULT WillRefreshDocument(IDocument* document, VARIANT_BOOL* evtStatus);

Parameters
document:

Document interface pointer of the document object being refreshed.

evtStatus:

Boolean set by the add-in telling Atoll if Refresh can continue or not.

Return Values
S_OK.

3.5.9.1.8

RefreshDocumentComplete Method
Event fired when a document has been refreshed from database.

HRESULT RefreshDocumentComplete(IDocument* document);

Parameters
document:

Document interface pointer of the document object which has been refreshed.

Return Values
S_OK.

3.5.9.1.9

WillArchiveDocument Method
Event fired when the user wants to archive a document into the database. It occurs just after the connection with the database is set up and after Atoll has checked if any changes have to be archived. If nothing requires archiving, this event is
not fired.

HRESULT WillArchiveDocument(IDocument* document, VARIANT_BOOL* evtStatus);

Parameters
document:

Document interface pointer of the document object being archived.

evtStatus:

Boolean set by an add-in telling Atoll if Archive can continue or not.

Return Values
S_OK.

3.5.9.1.10

ArchiveDocumentComplete Method
Event fired when the document has been archived in database. It occurs just before the connection with the database is
broken.

HRESULT ArchiveDocumentComplete(IDocument* document);

Parameters
document:

Document interface pointer of the document object which has been archived.

Return Values
S_OK.

Forsk 2007

AT260_DRG_E0

157

Developer Reference Guide

3.5.9.1.11

WillRun Method
Event fired when the user wants to start a calculation. If all is set to VARIANT_TRUE, this event occurs after the user has
confirmed that all previous calculations must be deleted.

HRESULT WillRun(IDocument* document, VARIANT_BOOL all, VARIANT_BOOL* evtStatus);

Parameters
document:

Document interface pointer of the document object whose calculation is requested.

all:
Boolean containing VARIANT_TRUE (True) if the user has requested Calculate All
(Ctrl+F7) or VARIANT_FALSE (False) if the user has requested Calculate (F7).
evtStatus:

Boolean set by the add-in telling Atoll if Run can continue or not.

Return Values
S_OK.

3.5.9.1.12

RunComplete Method
Event fired when the calculation has finished. It occurs after all tasks have completed.

HRESULT RunComplete(IDocument* document, VARIANT_BOOL all);

Parameters
document:
performed.

Document interface pointer of the document object where the calculation were

Return Values
S_OK.

3.5.9.1.13

LicenceAcquireComplete
This feature enables the user to log Atoll licence token usage from an add-in. Licence token consumption is available
globally for all Atoll instances running on one licence server using a dedicated application (monitor.exe).
External licence tokens are not tracked by this event. Licence events for the Measures module will be available for autoconnected add-ins only.
Fired when one licence token is acquired.

HRESULT LicenceAcquireComplete([in,
lModuleID);

unique]

IDocument

*pDocument,[in]

long

Parameters
pDocument:

IDocument interface pointer of the Atoll document that needed one licence token.

lModuleID:

ID of the licence token that has just been acquired.

Return Values
S_OK.

Remarks
lModuleID will be one of these constant values:

LICENCE_GSMTDMA
LICENCE_MW
LICENCE_MEASURES
LICENCE_AFP
LICENCE_PACK3G
LICENCE_UMTS
LICENCE_CDMA
LICENCE_TDSCDMA
LICENCE_WIMAX
For LICENCE_MEASURES token, pDocument will be NULL.

Module identifiers used when licence application events are fired:

const long LICENCE_GSMTDMA = 2;

const long LICENCE_MW = 4;
const long LICENCE_MEASURES = 8;

158

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

const long LICENCE_AFP = 16;

const long LICENCE_PACK3G = 32;
const long LICENCE_UMTS = 64;
const long LICENCE_CDMA = 128;
const long LICENCE_TDSCDMA = 256;
const long LICENCE_WIMAX = 512;

3.5.9.1.14

LicenceReleaseComplete
This feature enables the user to log Atoll licence token usage from an add-in. Licence token consumption is available
globally for all Atoll instances running on one licence server using a dedicated application (monitor.exe).
External licence tokens are not tracked by this event. Licence events for the Measures module will be available for autoconnected add-ins only.
Fired when one licence token is released.

HRESULT LicenceReleaseComplete([in, unique] IDocument *pDocument, [in] long

lModuleID);
Parameters
pDocument:

IDocument interface pointer of the Atoll document that just released the licence token.

lModuleID:

ID of the licence token that has just been acquired.

Return Values
S_OK.

Remarks
lModuleID will be one of these constant values:

3.5.9.2

LICENCE_GSMTDMA
LICENCE_MW
LICENCE_PACK3G
LICENCE_UMTS
LICENCE_CDMA
LICENCE_TDSCDMA
LICENCE_WIMAX

IAddin Interface
An external tool must expose an Add-in COM object by implementing the IAddin interface in order to be loaded by Atoll.
When Atoll finds an object in the registry implementing the category CATID_AtollAddins, it tries to load the Add-in if AutoConnect is set to True. Otherwise, this will be done later when the user selects the add-in in the Add-ins dialog (read Tutorials Step 2 to learn more about this option).
Loading an add-in means that Atoll creates an instance of this add-in and, when successful, calls the OnConnection
method of this object.

IAddIn outgoing interface

HRESULT OnConnection(IApplication* app, VARIANT_BOOL bFirstTime, long cookie,
VARIANT_BOOL* status )
HRESULT OnDisconnection(VARIANT_BOOL bLastTime)
Notes:

3.5.9.2.1

Add-in connection status between two consecutive Atoll sessions is stored in the system registry from Atoll
version 2.4.0.

Connecting an External Tool to a Running Session of Atoll

When a new Atoll session begins, Atoll looks in the registry to see which add-ins are available. An available add-in must
implement a specified category (whose CATID is necessarily CATID_AtollAddins). With this registry information Atoll is
able to list all add-ins, which normally implement the IAddin interface. According to the connection option set for the addin in the registry, the add-in is loaded or left unloaded.
The different choices are:

To automatically connect the add-in at the very beginning of an Atoll session

To connect the add-in only when the user asks for it.

Each add-in exposes an AddIn object by implementing the COM IAddin interface. When connection is requested, the
add-in receives an application object as an IApplication interface. This interface represents the Atoll Application. The add-

Forsk 2007

AT260_DRG_E0

159

Developer Reference Guide

in will be able to get Atoll session information from this interface, to manage documents (such as save, open, ) and to
add its own commands.
The connection is actually operational once the add-in object returns S_OK from the OnConnection method of IAddin
interface. The initialization of the add-in is performed in several steps within the OnConnection method depending on the
purpose of the external tool:

Calling the SetAddinInfos method of the application (to tell the application which object implements commands
and how to load resources)
Adding commands
Informing the application that the add-in wants to receive the fired events or not

The add-in is disconnected when the user unchecks it in the add-ins dialog. The add-in must release the application when
it is disconnected (IApplication interface).

3.5.9.2.2

Adding Commands
While some add-ins are written to automate some Atoll tasks, others can be requested by the user to perform a specific
job. To do so, the add-in has to add its own menu command or toolbar in Atoll. According to the connection mode, these
commands may be added once an Atoll session starts or even later.
External commands are added when implementing the OnConnection method. The identifier of the toolbar and the module
instance are input parameters of the SetAddinInfo method.
When the user selects an add-in item in the Tools menu, Atoll will send the command to this add-in using the dispatch
mechanism. This means that Atoll must know the object that implements this IDispatch COM interface. In the wizard example, it is the same object as the one implementing the IAddin COM interface.
The AddCommand method mainly tells Atoll the name of the command displayed in the GUI and the method name used
in the add-in implementation. A command is eventually added in the Tools menu of Atoll. It can also optionally appear in
a toolbar as well. If no toolbar is provided, no resource id is needed (pass 1 as parameter) in SetAddinInfo and pass
VARIANT_FALSE in AddCommand.
All commands must be defined in the interface definition of the object. A command has no parameter. Atoll always waits
untill the function returns, that means that an add-in must be carefully designed so as not to decrease Atolls performance.
Macros written in VBScript cannot add any command but can add icons in a toolbar (see 3.4.1 Adding Macros in Atoll).

3.5.9.2.3

OnConnection Method
Method called by Atoll when it is loading the add-in. If this method returns S_OK, the add-in is loaded and according to its
purpose will be able to receive events and commands etc.

HRESULT OnConnection(IApplication* app, VARIANT_BOOL bFirstTime,long cookie,

VARIANT_BOOL* status );
Parameters
App:
being loaded.

Application interface pointer of the top-level Application object, in which the add-in is

bFirstTime:
Boolean that equals VARIANT_TRUE only the first time the add-in is being
connected. If the add-in has been connected and then disconnected, the next OnConnection will set bFirstTime to
VARIANT_FALSE.
cookie:
Long value set by Atoll representing an identifier of the add-in. The add-in must send
back this identifier to Atoll when setting information or adding commands.
status:
otherwise, VARIANT_FALSE.

Boolean set by the add-in that returns VARIANT_TRUE if OnConnection succeeds,

Return Values
S_OK.

3.5.9.2.4

OnDisconnection Method
Method called by Atoll when the add-in is being disconnected.

HRESULT OnDisconnection(VARIANT_BOOL bLastTime);

Parameters
bLastTime:
Boolean set by Atoll to VARIANT_TRUE when the Atoll session is closing. When the
add-in is being disconnected because the user has deselected it in the add-ins dialog, bLastTime equals
VARIANT_FALSE.

Return Values
S_OK.

160

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Notes:

Read Shutting down Atoll to be sure to write a safe add-in.

3.5.10

Rules, Contracts and Advices

3.5.10.1

Error Handling
No exception can be thrown between Atoll and an add-in. Each error must be notified by returning an HRESULT error
code. When a method from Atoll returns an HRESULT other than S_OK, the add-in can extract error information by
requesting the IErrorInfo interface. In the same way, if the add-in supports IErrorInfo (i.e. implements IsupportErrorInfo)
interface, Atoll will be able to extract meaningful information from the error code when you write for instance:

return Error(This is my message, __uuidof(IAddin));

Read COM documentation to learn more about error handling. The ReadSignal example in ITabularData interface shows
you how to handle unsuccessful results due to add-in or Atoll failure.

3.5.10.2

Automatic Reference Counting

Objects created by an Atoll method are returned locked (with AddRef) to the add-in. When the add-in has finished using
them, it must release them. References to objects sent to the add-in are only valid for the duration of the add-in method's
call (except the IApplication object, which is valid as long as the add-in remains connected). One safer method to release
a pointer at the right time is to use it through the ATL CComPtr class.

3.5.10.3

MFC Support Considerations

3.5.10.3.1

BSTR and VARIANT Types

A BSTR is a pointer to a wide character string used by Automation data manipulation functions. You can use the wrapper
class _bstr_t or use CString if your project is MFC compatible.
VARIANT type is used by Automation in the same way. Use for instance the wrapper class _variant_t to handle a variant.

3.5.10.3.2

Resource Access
In order for the add-in to access the dlls defined resources and not the application's, the add-ins developer has to call the
following macro in each function:

AFX_MANAGE_STATE(AfxGetStaticModuleState());
Refer to Microsoft Online Help to obtain precisions on this call.

3.5.10.4

Shutting Down Atoll

A local variable is normally destroyed when the procedure, in which it was declared, finishes execution. However, it is good
programming practice to explicitly destroy an application-level object variable, used to automate another application, by
setting it equal to the Nothing keyword or NULL in C++. Doing this frees any remaining memory used by the variable. For
Atoll, you should also call the Quit method in order to free up the memory it is using.

3.5.11

Enumerations
Enumerations are used to specify constants. Two categories of enumerations are defined hereafter.
The first category refers to all enumerations defined in Atoll library. All of them are prefixed with Ato (for Atoll). The second
category refers to all enumeration defined in FSKGISLib Library. All of these are prefixed with fg.
Note that VBScript does not accept enumerations. No errors will be thrown. But when using a constant name, its value is
random and so is the result. In VBScript the value of a constant must be used rather than its name.

3.5.11.1

AtoSaveStatus
Constant

Value

Description

atoSaveSucceeded

Document has been successfully saved.

atoSaveCanceled

Save changes in the document has been cancelled by the user.

See 3.5.8.1.13 Quit, 3.5.8.3.14 Close and 3.5.8.2.9 CloseAll methods.

3.5.11.2

Forsk 2007

AtoSaveChanges
Constant

Value

Description

atoSaveNo

Document is closed without being saved.

AT260_DRG_E0

161

Developer Reference Guide

atoSaveYes

Document is saved before being closed.

atoSavePrompt

The user is prompted whether if the document must be saved before

closed.

See 3.5.8.1.13 Quit, 3.5.8.3.14 Close and 3.5.8.2.9 CloseAll methods.

3.5.11.3

AtoRefreshPriority
Constant

Value

Description

atoCancelChanges

All changes in the document are cancelled before database is reloaded.

atoSkipChanges

Refreshes only data that have not been modified.

See 3.5.8.3.17 Refresh method.

3.5.11.4

AtoArchiveStatus
Constant

Value

Description

atoArchiveSaveSucceeded

Archiving has succeeded. No conflicts.

atoArchiveCanceled

Archiving has been cancelled (by the user or because conflicts occurred).

Constant

Value

Description

atoMaximized

Maximized (enlarged to maximum size).

atoNormal

Normal (Default).

atoMinimized

Minimized (minimized to an icon in the task bar).

See 3.5.8.3.18 Archive method.

3.5.11.5

AtoWindowStatus

See 3.5.8.1.9 WindowStatus property.

3.5.11.6

AtoLogType
Constant

Value

Description

atoInfo

Uses the information icon for the message.

atoError

Uses an error icon for the message.

atoWarning

Uses a warning icon for the message.

Constant

Value

Description

atoEQ

(EQual) Specifies that the search is for the first value equal to searchVal.

atoLT

(Strictly Lower Than) Specifies that the search is for the first value less
than searchVal.

atoLE

(Lower or Equal) Specifies that the search is for the first value less than or
equal to searchVal.

atoGE

(Greater or Equal) Specifies that the search is for the first value greater
than or equal to searchVal.

atoGT

(Strictly Greater Than) Specifies that the search is for the first value greater
than searchVal.

atoNE

(Not Equal) Specifies that the search is for the first value not equal to
searchVal.

Constant

Value

Description

atoDbm

Transmission unit is dBm.

atoWatt

Transmission Unit is Watt.

atoKWatt

Transmission Unit is KWatt.

See 3.5.8.1.14 LogMessage method.

3.5.11.7

AtoCompareOp

See 3.5.8.8.11 Find method.

3.5.11.8

162

AtoTransmissionUnit

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

See 3.5.8.3.11 TransmissionUnit property.

3.5.11.9

AtoReceptionUnit
Constant

Value

Description

atoDbmRx

Reception Unit is dBm.

atoDbMicroVolt

Reception Unit is DbVolt.

atoDbMicroVoltMeter

Reception Unit is DbVolt /meter.

See 3.5.8.3.12 ReceptionUnit property.

3.5.11.10

AtoDistanceUnit
Constant

Value

Description

atoM

Distance unit is meter.

atoKm

Distance unit is kilometre.

atoMiles

Distance unit is miles.

See 3.5.8.3.13 DistanceUnit property.

3.5.11.11

AtoRadiatedPowerUnit
Constant

Value

Description

atoRadiatedPowerEIRP

Radiated power is EIRP.

atoRadiatedPowerERP

Radiated power is ERP.

See 3.5.8.6.3 RadiatedPowerUnit property.

3.5.11.12

AtoAntennaGainUnit
Constant

Value

Description

atoAntennaGainDbi

Antenna gain unit is dBi.

atoAntennaGainDbd

Antenna gain unit is dBd.

See 3.5.8.6.4 AntennaGainUnit property.

3.5.11.13

AtoHeightOffsetUnit
Constant

Value

Description

atoHeightOffsetM

Height offset unit is metre.

atoHeightOffsetFeet

Height offset unit is feet.

See 3.5.8.6.5 HeightOffsetUnit property.

3.5.11.14

AtoRootType
Constant

Value

Description

atoData

Requested tab is the data tab.

atoGeo

Requested tab is the geo tab.

atoModule

Requested tab is the module tab.

See 3.5.8.3.25 GetRootFolder meethod.

3.5.11.15

AtoRowFilter
Constants to filter only modified, added, or deleted rows.

Constant

Value

Description

atoRowFilterNone

No filter.

atoRowFilterModifiedOrNew

Filter to retain only modified or new rows.

atoRowFilterDeleted

Filter to retain only deleted rows.

See 3.5.8.9.6 Filter meethod.

Forsk 2007

AT260_DRG_E0

163

Developer Reference Guide

3.5.11.16

AtoRowStatus
All possible row statuses.

Constant

Value

Description

atoRowStatusNew

Row has been added.

atoRowStatusModified

Row has been modified.

atoRowStatusDeleted

Row has been deleted.

atoRowStatusUnmodified

Row is unmodified.

When you open a document from database, atorowstatus is set to Unmodified and original values are set for all records.
When you archive or refresh your document, atorowstatus is set to Unmodified and original values are set for all records
that have been archived or refreshed.
When you create a new record in the document in Atoll, atorowstatus is set to New and original value is set to Null.
When you modify any record in the document in Atoll, atorowstatus is set to Modified. If you undo the modification in the
record, atorowstatus is set to Unmodified.
See 3.5.8.9.11 RowStatus meethod.

3.5.11.17

GeographicUnit
Constant

Value

Description

fgUnspecifiedUnit

-1

Value when nothing has been defined.

FgMeter

Length unit is meter.

FgKilometer

Length unit is kilometre.

FgFoot

Length unit is foot.

FgLink

FgChain

FgYard

Length unit is Yard.

FgNauticalMile

Length unit is Nautical Mile.

FgMile

Length unit is Mile.

FgRadian

100

Longitude / Latitude units are radian.

FgDegree

101

Longitude / Latitude units are degree.

FgGrad

102

Longitude / Latitude units are grads.

FgArcMinute

103

Longitude / Latitude units are minutes.

FgArcSecond

104

Longitude / Latitude units are seconds.

See 3.5.8.17.14 Unit property of CoordinateSystem object.

3.5.11.18

ProjectionMethod
Constant

Value

Description

fgUndefinedProjection

Value when nothing has been defined.

fgNoProjection

This system has no projection method.

fgLambertConfConic1SP

Lambert Conf Conic1 SP.

fgLambertConfConic2SP

Lambert Conf Conic2 SP.

fgMercator

Mercator.

fgCassiniSoldner

Cassini Soldner.

fgTransverseMercator

Transverse Mercator.

fgTransvMercatorSouthOriented

Transverse Mercator South Oriented.

fgObliqueStereographic

Oblique Stereographic.

fgNewZealandMapGrid

New Zealand Map Grid.

fgHotineObliqueMercator

10

Hotine Oblique Mercator.

fgLabordeObliqueMercator

11

Laborde Oblique Mercator.

fgSwissObliqueCylindrical

12

Swiss Oblique Cylindrical.

fgObliqueMercator

13

Oblique Mercator.

fgUTMProjection

14

UTM Projection.

See 3.5.8.17.10 ProjMethod property and 3.5.8.17.13 SetProjection method of CoordinateSytem object.

164

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

3.5.11.19

ProjParameterIndices
Constant

Value

Description

fgUTMZoneNumber

Number of UTM zone.

fgLongitudeOfOrigin

Longitude of the origin of the zone.

fgLatitudeOfOrigin

Latitude of the origin of the zone.

fgFalseEasting

False "easting".

fgFalseNorthing

False "northing".

fgScaleFactorAtOrigin

Scaling factor at the origin.

fgLatitudeOf1stParallel

Latitude of the first parallel.

fgAzimuthOfCentralLine

Azimuth of the central line.

fgLatitudeOf2ndParallel

Latitude of the second parallel.

fgAngleFromRecttifiedToSkewedGrid

See 3.5.8.17.11 ProjParameter method of CoordinateSytem object.

3.5.12

Raster Data API

This is a specific definition of interfaces, enumerations and structures dedicated to the display and management of smart
graphic objects inside Atoll platform.

3.5.12.1

Raster Data API Structures

3.5.12.1.1

GEOPOINT Structure
GEOPOINT is the structure for a geographic position.

typedef struct _GEOPOINT

{
double x, y;
} GEOPOINT;
Fields of the GEOPOINT structure:

3.5.12.1.2

X abscissa of the point.

Y ordinate of the point.

GEOSIZE Structure
GEOSIZE is the structure for a geographic size (e.g. pixel size).

typedef struct _GEOSIZE

{
double xsize, ysize;
} GEOSIZE;
Fields of the GEOSIZE structure:

3.5.12.1.3

xsize

Size along the X axis.

ysize

Size along the Y axis.

GEORECT Structure
GEORECT is the structure for a geographic rectangle.

typedef struct _GEORECT

{
double xmin, ymin, xmax, ymax;
} GEORECT;
Fields of the GEORECT structure:

Forsk 2007

xmin

Min abscissa of the rectangle (normally west).

ymin

Min ordinate of the rectangle (normally south).

xmax

Max abscissa of the rectangle (normally east).

AT260_DRG_E0

165

Developer Reference Guide

ymax

3.5.12.1.4

Max ordinate of the rectangle (normally north).

GEOGRID Structure
GEOGRID is the structure for a grid of pixels.

typedef struct _GEOGRID

{
GEOPOINT origin;
GEOSIZE

resolution;

SIZE

size;

} GEOGRID;
A GEOGRID can be north oriented or south oriented.
Fields of the GEOGRID structure:
origin
For a north oriented grid, this is the south-west corner of the pixel at the south-west
corner of the grid. For a south oriented grid, this is the north-west corner of the pixel at the north-west corner of the grid.
resolution
The size of a pixel in geographic coordinates. For a north oriented grid, resolution.ysize is a positive number. For a south oriented grid, resolution.ysize is a negative number.
size
are positive numbers.

The size of the grid in pixels (number of columns, number of rows). size.cx and size.cy

For both cases, the geographic coordinates of the centre of pixel (i,j) are:
(origin.x + i * resolution.xsize + resolution.xsize / 2, origin.y + j * resolution.ysize + resolution.ysize / 2)

3.5.12.1.5

RASTERBUFFER Structure
RASTERBUFFER is a structure for describing a memory buffer that can contain raster data. It is similar to the BITMAP
format defined in WIN32.

typedef struct _RASTERBUFFER

{
LONG width, height, scanline;
[ref, size_is(height*scanline)] BYTE *buffer;
} RASTERBUFFER;
Fields of the RASTERBUFFER structure:
width

Width of the buffer in pixels.

height

Height of the buffer in pixels.

scanline

Memory offset, in bytes, between pixel 0 of row i and pixel 0 of row i+1.

buffer

Address of pixel (0,0).

Note that scanline can be a negative number. In which case, row 0 of the buffer is at the end of the memory block.

3.5.12.2

Enumerations
typedef enum RasterDataType {fgUnsignedInteger = 0x100, fgInteger=0x200, fgReal=0x300, fgColor=0x400} RasterDataType;
typedef enum RasterType
{
fgUndefinedRasterType = 0,
fgUInt_1

= fgUnsignedInteger|1,

fgUInt_4

= fgUnsignedInteger|4,

fgUInt_8

= fgUnsignedInteger|8,

fgUInt_16 = fgUnsignedInteger|16,
fgUInt_32 = fgUnsignedInteger|32,
fgInt_8

= fgInteger|8,

fgInt_16

= fgInteger|16,

fgInt_32

= fgInteger|32,

fgReal_32 = fgReal|32,
fgReal_64 = fgReal|64,

166

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

fgColor_24= fgColor|24
} RasterType;
cpp_quote("inline int NBits(RasterType t) {return int(t)&0xFF;}")
RasterType enumeration defines the types supported for a pixel in a raster. This is the combination of a data type
(unsigned integer, signed integer, real or colour value) and a size in bits.
Supported types are:

3.5.12.3

Unsigned integer with 1, 4, 8, 16, 32 bits per pixel.

Signed integer with 8, 16, 32 bits per pixel.
Real with 32 or 64 bits per pixel.
Colour (RGB) with 24 bits per pixel.

IGeoCoverage Interface
An object implementing IGeoCoverage defines a numeric valued function on a spatial domain. Its main feature is that it
can be rasterized, i.e. the values for each pixel of a GEOGRID can be retrieved in an efficient way. The underlying structure
is not necessarily raster data. It can be a set of raster data with multiple resolutions or a set of polygons with an associated
numeric attribute.
Methods in Vtable order:

3.5.12.3.1

IUnkown

Description

QueryInterface

Returns pointer to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IGeoCoverage

Description

get_DataType

Returns the numeric type of the data defined by this coverage.

get_NoDataValue

Returns the value used by this coverage as an indicator meaning no data available
at this location.

get_BoundingBox

Returns the rectangle where this coverage is defined.

Get_OptimalResolution

Returns the best resolution to use for a specific area

Rasterize

Fills a memory buffer with values defined at each pixel centre of a grid.

get_DataType Method
HRESULT get_DataType([out, retval]RasterType *pType);
Parameters
pType:

Receives the data type of the coverage.

Return Values
E_POINTER, if pType is NULL.
S_OK means that the data type was successfully returned.

3.5.12.3.2

get_NoDataValue Method
HRESULT get_NoDataValue([in]WORD
*pBuff);

buffSize,

[out,

size_is(buffSize)]

BYTE

Parameters
buffSize:

The size, in bytes, of the buffer pointed by pBuff.

pBuff:

The address where the value should be copied.

Return Values
S_FALSE, if this coverage is defined everywhere in its bounding box. In this case no no data value is needed.
E_INVALIDARG, if the buffer is too small to contain the value.
E_POINTER, if pBuff is NULL.
S_OK means that a no data value was copied in the buffer.

Forsk 2007

AT260_DRG_E0

167

Developer Reference Guide

Notes:

3.5.12.3.3

The buffer pBuff should be considered as a RASTEBUFFER with width=1, height=1 and scanline=buffSize.
For example, if the data type is fgUInt_1 (1 bit per pixel), the bit must be copied to the most significant bit of
the first byte pointed by pBuff.

get_BoundingBox Method
HRESULT get_BoundingBox([out]GEORECT *bounds);
Parameters
bounds:

Receives the limits of the spatial domain for this coverage.

Return Values
S_OK means that the limits were successfully copied to bounds.

Remark
This function will be called by Atoll at the start of the loading process. The object will not be loaded at all if the bounding
box does not intersect the area displayed on the screen.

3.5.12.3.4

get_OptimalResolution Method
HRESULT get_OptimalResolution([in]const GEORECT *area, [out, retval]GEOSIZE
*resolution);
Parameters
area:

Defines the zone on which the optimal resolution is requested.

resolution:

Value of the optimal resolution.

Return Values
S_FALSE, if there was a problem to get the optimal resolution
E_POINTER, if area or resolution is NULL.
S_OK means that the optimum resolution was provided
Notes:

3.5.12.3.5

Gets the best available resolution on area which must be included in the limits of the spatial domain
returned by get_BoundingBox().

An IGeoCoverage containing polygons must conventionally return (0,0)

An IGeoCoverage composed of several raster maps of different resolutions must return the value of the
highest resolution raster map intersecting the area.

An object implementing IGeoRaster must provide the same value as the member resolution provided by the
get_Grid function (cf. get_Grid below).

Rasterize Method
HRESULT
Rasterize([in]const
GEOGRID
*grid,
[in]DWORD
flags,
[in]
IProgressCallback2 *pgr, [in] const POINT *pDst, [in, out]RASTERBUFFER *pBuff);
Parameters
grid:

Defines the regularly spaced points from where coverage values are to be retrieved.

flags:

Reserved for future use. Must be zero.

pgr:
An IProgressCallback2 that can be used to provide feedback to the user. This parameter is allowed to be NULL. In which case, no feedback should be provided to the user.
pDst:

Point in the buffer pBuff where the pixel (0, 0) of the grid should be copied.

pBuff:
Receives the requested values. This buffer can be bigger than the requested grid. In
this case pDst and size define the area of the buffer where values are actually copied.
Notes:

168

Atoll is responsible for allocating and liberating this memory buffer.

pBuff is passed as [in,out] parameter because it contains an in-part, the organization of memory (width,
height, scanline), and an out-part, the buffer.

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Return Values
E_ABORT, if the operation was cancelled by the user (see 2.3.3.8 IProgressCallback2 interface).
E_FAIL, if an error occurred.
E_NOTIMPL, if this function is not implemented. This return code is legal only if the object also supports the IGeoRaster
interface.
Any other error code than E_FAIL implies that the object should also support the ISupportsErrorInfo interface in order to
enable the caller to display an error message.
S_OK, if the values were successfully copied.
Notes:

The values requested are the coverage values at the pixel centre of the grid.

In order to facilitate the implementation of this function, the following assumptions are the responsibility of
the caller:
- All pixel centres of the grid must lie within the rectangle returned by get_BoundingBox.
- If the object supporting this interface also supports IGeoRaster, the requested grid must have the same
orientation and a lower resolution than the one returned by get_Grid (the caller should flip the buffer if
necessary).
- Although it is legal to return E_NOTIMPL when implementing IGeoRaster also, in most case this is not
optimal. This is because the caller has no knowledge of the internal representation of the data (tiling,
compression, presence of overviews etc).

Remark
This function will be called by Atoll if the resolution of the IGeoRaster happens to be higher (lower numeric value) than the
one requested by the map grid to draw. As the underlying representation of data is not known by Atoll, under-sampling
task is at first left to the object. If the object does not implement this, it should return E_NOTIMPL value. Atoll will then call
ReadDataBlock value in return to get high-resolution values and under-sample it itself. Otherwise, ReadDataBlock will not
be called. If the resolution of the IGeoRaster is lower (higher numeric value), then ReadDataBlock will be called and Atoll
will over-sample it itself.

3.5.12.4

IGeoRaster Interface
This interface defines the true raster data. As it is derived from IGeoCoverage, it can provide an efficient way to obtain a
sub-sampled matrix via the Rasterize function.
Objects implementing this interface and reading their data directly from disk will have to be registered under the new category CATID_AtollFileFormat. Objects implementing this interface will be created by add-ins.
Methods in Vtable order:

3.5.12.4.1

IUnknown

Description

QueryInterface

Returns pointer to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IGeoCoverage

Description

get_DataType

Returns the numeric type of the data defined by this coverage.

get_NoDataValue

Returns the value used by this coverage as an indicator meaning no data available
at this location.

Get_OptimalResolution

Returns the best resolution to use for a specific area

get_BoundingBox

Returns the rectangle where this coverage is defined.

Rasterize

Fills a memory buffer with values defined at each pixel centre of a grid.

IGeoRaster

Description

get_Grid

Returns the GEOGRID of the underlying data

ReadDataBlock

Copies a rectangle of the underlying matrix into a memory buffer.

get_Grid Method
HRESULT get_Grid([out] GEOGRID *pGrid);
Parameters
pGrid:

Forsk 2007

Receives the grid of the underlying data.

AT260_DRG_E0

169

Developer Reference Guide

Return Values
S_OK

Remark
This function will be called by Atoll only if the data really requires being drawn on the screen.

3.5.12.4.2

ReadDataBlock Method
HRESULT
ReadDataBlock([in]const
POINT
*pSrc,
IProgressCallback2 *pgr, [in] const POINT *pDst,

[in]const

SIZE

*pSize,

[in, out]RASTERBUFFER *pBuff);

Parameters
pSrc:
Defines the origin, in pixel coordinates, of the block to be copied. If the grid returned
by get_Grid is North-oriented, this will be the bottom left pixel of the block. If the grid returned by get_Grid is South-oriented,
this will be the top left pixel of the block.
pSize:

Defines the size of the block to be copied.

pgr:
An IProgressCallback2 that can be used to provide feedback to the user. This parameter is allowed to be NULL. In which case, no feedback should be provided to the user.
pDst:

Point in the buffer pBuff where the pixel (0, 0) of the block should be copied.

pBuff:
Receives the requested values. This buffer can be bigger than the requested block.
In this case pDst and size define the area of the buffer where values are actually copied.
Notes:

Atoll is responsible for allocating and liberating this memory buffer.

pBuff is passed as [in,out] parameter because it contains an in-part, the organization of memory (width,
height, scanline), and an out-part, the buffer.

Return Values
E_ABORT, if the operation was cancelled by the user (see 2.3.3.8 IProgressCallback2 interface).
E_FAIL, if an error occurred.
Any other error code than E_FAIL implies that the object should also support the ISupportsErrorInfo interface in order to
enable the caller to display an error message.
S_OK means that the values were successfully copied.

3.5.12.5

IColorTable Interface
Georeferenced images are an important subset of georeferenced rasters because they can be directly displayed on a map
without further interpretation.
An object supporting IGeoRaster is considered an image if either its data type is fgColor_24 (each pixel is an RGB value),
or its data type has less than 8 bits and it supports the IColorTable interface. The IColorTable interface provides a colour
interpretation for each pixel value.
Methods in Vtable order:

3.5.12.5.1

IUnknown

Description

QueryInterface

Returns pointer to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IGeoCoverage

Description

get_ColorCount

Returns the number of colours in the colour table.

get_Colors

Returns the list of colours corresponding to pixel values.

get_ColorCount Method
HRESULT get_ColorCount([out]LONG *pVal);
Parameters
pVal:
Receives the number of colours in the table. Colour tables always begin at pixel value
0, i.e. provide colour interpretation for pixel values in the range [0,*pVal[.

170

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

Return Values
S_OK is the only legal Return Values for this function.

3.5.12.5.2

get_Colors Method
HRESULT get_Colors([in]LONG start, [in]LONG count, [out, size_is(count)]COLORREF *pColors);
Parameters
start:

Index, in the table, of the first value to be returned.

count:

The number of colours to be returned.

pColors:

Address of the buffer where colours should be copied.

Return Values
S_OK is the only legal Return Values for this function.

3.5.12.6

Optional Interfaces For The GeoRaster Object

In terms of simplicity and performance, it is better to send the mouse click events directly to the IGeoRaster object instead
of sending them to the IAddin object.
To handle these events correctly, the object implementing the IGeoRaster interface must also implement the new
IActiveMapObject interface.

3.5.12.6.1

IActiveMapObject Method
An object implementing this interface will receive Windows events.
Methods in Vtable order:

3.5.12.6.2

IUnknown

Description

QueryInterface

Returns pointer to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IActiveMapObject

Description

QueryHitPoint

This method indicates whether a point is within an object.

OnWindowMessage

Atoll calls this method to dispatch Windows message to the object.

QueryDataTip

Returns a string to be displayed in a balloon popup window.

QueryHitPoint Method
HRESULT QueryHitPoint([in]const GEOPOINT *pPoint, [in]DWORD flags, [in]IUnknown* pMap);
Parameters
pPoint:

The geographic position of the point to be queried.

flags:

reserved for future use.

pMap:

reserved for future use.

Return Values
S_FALSE, if the point is outside the object or over a transparent part.
E_NOTIMPL, if the object does not implement this function.
In this case Atoll will try any other mean to determine if the point is within the object. For example, if the object implements
IGeoRaster, Atoll will check that the point is inside the grid of the raster and that the pixel value at that point is not the
noDataValue of the raster.
S_OK means that the point is within an opaque part of the object.

3.5.12.6.3

OnWindowMessage Method
HRESULT OnWindowMessage([in] const MSG *msg [in]const GEOPOINT
[in]DWORD flags, [in]IUnknown* pMap, [out]LRESULT *plResult);

Forsk 2007

AT260_DRG_E0

*pPoint,

171

Developer Reference Guide

Parameters
msg:

The Windows message forwarded to the object.

pPoint:
The geographic position where the mouse cursor was when the event occurred. This
parameter is NULL if the event occurred in the Atoll Explorer window.
flags:

reserved for future use.

pMap:

reserved for future use.

plResult:

Pointer to result code for the window message as defined in the Windows API.

Return Values
S_OK means that the message was handled and no further processing is necessary.
S_FALSE, if the message was not handled. Let Atoll do the default processing.
Notes:

When the message is on a map window, Atoll calls QueryHitPoint with the coordinate of the mouse cursor.
OnWindowMessage is called only if QueryHitPoint returns S_OK

The following messages are dispatched to the object under the mouse cursor:
WM_MOUSEMOVE
WM_DEADCHAR
WM_SETCURSOR
WM_SYSKEYDOWN
WM_XBUTTONDOWNa
WM_SYSKEYUP
WM_XBUTTONUP
WM_SYSDEADCHAR
WM_XBUTTONDBLCLK
WM_HELP
WM_KEYDOWN
WM_CANCELMODE
WM_KEYUP
WM_CHAR

a.

3.5.12.6.4

X stands for R (Right Button) or L (Left button)

QueryDataTip Method
HRESULT QueryDataTip([in]const GEOPOINT *pPoint, [in]DWORD flags, [in]IUnknown*
pMap, [out]LPOLESTR *ppszTip);
Parameters
pPoint:

The geographic position of the point to be queried.

flags:

reserved for future use.

pMap:

reserved for future use.

ppszTip:
The string to be displayed. This string must be allocated with CoTaskMemAlloc. The
caller is responsible to free it with CoTaskMemFree.

Return Values
S_FALSE, if there is no Tip displayable at this position
E_NOTIMPL, if the object does not implement this function.
S_OK means a string was returned in ppszTip.

3.5.12.7

IContextMenu Interface
The IContextMenu interface is called by Atoll to merge a shortcut menu associated with an Atoll Explorer window object.

Object

ContextMenu

172

IContextMenu functions
HRESULT GetCommandString(UINT_PTR idCmd, UINT
uFlags, UINT *pwReserved, LPSTR pszName, UINT
cchMax);

AT260_DRG_E0

Property (P)
Method (M)
M

Forsk 2007

Chapter 3: General API

3.5.12.7.1

HRESULT QueryContextMenu(HMENU hmenu, UINT

indexMenu, UINT idCmdFirst, UINT idCmdLast, UINT
uFlags);

HRESULT InvokeCommand(LPCMINVOKECOMMANDINFO
lpici);

GetCommandString Method
This method is reserved for future use.

HRESULT GetCommandString(UINT_PTR idCmd, UINT uFlags, UINT *pwReserved, LPSTR

pszName, UINT cchMax);
Parameters
The parameters are reserved for future usage.

Return Values
Should return E_NOTIMPL to show that it is not implemented.

3.5.12.7.2

QueryContextMenu Method
Adds commands to a shortcut menu.

HRESULT QueryContextMenu(HMENU hmenu, UINT indexMenu, UINT idCmdFirst, UINT idCmdLast, UINT uFlags);
Parameters
hmenu:

Handle to the menu. The handler should specify this handle when adding menu items.

indexMenu:

Zero-based position at which to insert the first menu item.

idCmdFirst:

Minimum value that the handler can specify for a menu item identifier.

idCmdLast:

Maximum value that the handler can specify for a menu item identifier.

uFlags:

CMF_NORMAL indicates normal operation.

Return Values
If successful, returns an HRESULT value that has its severity value set to SEVERITY_SUCCESS and its code value set
to the offset of the largest command identifier that was assigned, plus one. For example, assume that idCmdFirst is set to
5 and you add three items to the menu with command identifiers of 5, 7, and 8. The Return Values should be
MAKE_HRESULT(SEVERITY_SUCCESS, 0, 8 - 5 + 1).
Otherwise, returns an OLE error value.

Remarks
This method should call either InsertMenu or InsertMenuItem to insert its menu items into the menu specified by hmenu.
The indexMenu parameter holds the index that should be used for the first menu item. The identifier of each menu item
must fall within the range defined by idCmdFirst and idCmdLast.
A common practice is to set the first command identifier to idCmdFirst (an offset of zero) and increment the offset for each
additional command by one. This practice ensures that you do not exceed idCmdLast and preserves the range of identifiers that are available for use by other handlers. Store the offsets for reference because they can be used to identify the
command in subsequent calls to IContextMenu::InvokeCommand.

3.5.12.7.3

InvokeCommand Method
Carries out the command associated with a shortcut menu item.

HRESULT InvokeCommand(LPCMINVOKECOMMANDINFO lpici);

Parameters
lpici:
Reference to the command information structure CMINVOKECOMMANDINFO. This
is a data structure used to store the command, along with information about the command, such as its working directory
and any optional parameters. For a list of the structure's members, see the table below.

struct _CMInvokeCommandInfo {
DWORD cbSize;
DWORD fMask;
HWND hwnd;

Forsk 2007

AT260_DRG_E0

173

Developer Reference Guide

LPCSTR lpVerb;
LPCSTR lpParameters;
LPCSTR lpDirectory;
int nShow;
DWORD dwHotKey;
HANDLE hIcon;
} CMINVOKECOMMANDINFO,

*LPCMINVOKECOMMANDINFO;

Members:
cbSize:

The size of the CMINVOKECOMMANDINFO structure, in bytes.

fMask:

Not used.

hwnd:
Handle of the window to which the shortcut menu belongs. Can be used as the owner
of any message boxes or dialog boxes it displays.
lpVerb:
A 32-bit value containing the command being invoked, expressed as a menu-identifier
offset. Contains a menu-identifier offset of the command in the LOWORD, as expressed by MAKEINTRESOURCE(idOffset).
lpParameters:

Not used.

lpDirectory:

Not used.

nShow:

Not used.

dwHotKey:

Not used.

hIcon:

Not used.

Return Values
S_OK if the command was successfully invoked.
An appropriate error message if it was not successfully invoked.

3.5.12.8

Other Interfaces
In addition to the interfaces defined by the Atoll API, Atoll can also use the following standard COM interfaces:
1.
2.

ISpecifyPropertyPages: This interface is used by Atoll to display property pages associated with the object
IPersistStream: This interface is used by Atoll to serialize objects in Atoll Document files, without knowing the
semantics of these objects.
IPersistPropertyBag: This interface is used by Atoll to serialize objects in XML files (*.geo or *.cfg)

3.
Notes:

IPersistStream and ISpecifyPropertyPages are already documented for Propagation Models in the DRG.
They constitute an easy way to add property pages to items of the explorer and having the properties saved
in the .atl files and retrieved.

IPersistPropertyBag allows to save a "flat" view of some parameters, for example driver's parameters under
XML format.

3.6

Appendix

3.6.1

Predictions Tabular Data

174

Column Name

Type

Description

TX_ID

char (50)

Transmitter name.

LOCKED

Boolean

True if this prediction is locked, else False.

VALID

Boolean

True if the path loss matrix is valid, else False.

INVALID_CAUSE

Char(50)

Cause of invalidity (if above VALID => False).

SIZE

Integer

Size of the matrix in bytes.

PATHNAME

Char(255)

Contains EMBEDDED if storage is not external, else contains the

pathloss file name.

PATHLOSS

IUnknown

Contains a variant of VT_Unknown type, which is an IGridData interface.

This grid data contains the Main pathloss matrix for transmitter TX_ID.

SIGNAL

IUnknown

Contains a variant of VT_Unknown type, which is an IGridData interface.

This grid data contains the Main signal level matrix for transmitter TX_ID.

AT260_DRG_E0

Forsk 2007

Chapter 3: General API

LOWRES_PATHLOSS

IUnknown

Contains a variant of VT_Unknown type, which is an IGridData interface.

This grid data contains the Extended pathloss matrix for transmitter TX_ID

LOWRES_SIGNAL

IUnknown

Contains a variant of VT_Unknown type, which is an IGridData interface.

This grid data contains the Extended signal level matrix for transmitter
TX_ID.

Predictions tabular data is read-only except for LOCKED.

3.6.2

3.6.3

Zones Tabular Data

Column Name

Type

Description

NAME

Char(50)

Contains ComputationZone if this record is the computation zone.

Contains FoscusZone if this record is part of the focus zone.

POINTS

Variant

Contains an array of points as double values.

CONTOUR_NUM

Real

Contains the number of the contour.

POLYGON_NUM

Real

Contains the numer of the polygon.

Best Signal Export Add-in

This add-in is developed by Forsk and is available in the Downloads section of Forsks Support website. The add-ins
source code is available upon request. It may be seen as a good starters guide for the development of add-ins, demonstrating how to access radio data tables and computation results.

Forsk 2007

AT260_DRG_E0

175

Developer Reference Guide

176

AT260_DRG_E0

Forsk 2007

Chapter 4
Basic AFP API
This chapter describes the basic Atoll AFP API. The AFP API has been specifically designed for working with
Automatic Frequency Planning module in Atoll.

Developer Reference Guide

178

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

Basic AFP API

4.1

Introduction
Since its inception and first implementation (2003), Forsks AFP API has evolved to meet new requirements and challenges. It consists of a basic and an extended interface. In order to fully understand the AFP API, it is recommended to
read and understand the AFP Reference Guide as a prerequisite. This will enable the reader to grasp the role of the AFP
in Atoll and the role of the different entities in the AFP API interface.
The user can start working with the AFP API with the knowledge of the basic interface only. The extended (advanced)
interface of the AFP API can be used if such a need arises. Atoll itself ensures compatibility between the developments
based on the basic AFP API.
Therefore, the AFP API wizard creates a basic AFP class (using only the basic AFP API). The advanced AFP API is
explained in the next chapter.

4.2

AFP Model Tutorial

Refer to the chapter Propagation Model Tutorial and insert an ATL object of type AtollAfp Model instead of Atoll Propagation Model in Step 2.

4.3

Basic Definitions

4.3.1

Resource Number
This is an integer used to specify a resource.
Resource numbers that can be dealt with in Atoll AFP correspond to:

ARFCN Absolute Radio Frequency Channel Number

HSN Hopping Sequence Number
MAIO Mobile Allocation Index Offset
BSIC Base Station Identity Code
MAL
Mobile Allocation List

The AFP is instructed by the user through the API to assign certain resource types. For each of these resource types, the
AFP can ask for the quantity of resources needed (Demand = n) and the domain (D) from which to choose. This means
that it should assign n resources out of D.

4.3.2

Resource Group
This is a group of resource numbers.
The most common example is the Frequency group.

4.3.3

Grouping Scheme
It corresponds to a list of resource groups. The union of this group of groups is the domain. A Grouping scheme is, therefore, a resource domain containing one ore more resource groups. A resource may belong to more than one group in the
grouping scheme (domain).

4.3.4

MAL Mobile Allocation List

(Also known as Hopping Groups)
In Synthesised Frequency Hopping (SFH) mode, the MAL is a list of frequencies (i.e. the list of channel numbers that can
contain at most 64 values) between which a given TRX hops.
Usually, the MAL is the same for all TRXs of a given cell as all these TRX are synchronized. Other configurations are possible and, therefore, Atolls new data model enables MAL allocation at TRX level.

4.3.5

TRG TRX Group

A group of TRXs belonging to the same cell and dedicated to the same usage. TRX Groups facilitate the modelling of
concentric cells. In this case, there are two TRX Groups for each cell, i.e. TCH_inner_group and TCH_outer_group.
TRX Groups allow having exceptional quality requirements for special TRXs (for example, the ones supporting BCCH or
EGPRS timeslots).

Forsk 2007

AT260_DRG_E0

179

Developer Reference Guide

Here is a list of properties that are determined at the TRX-group level instead of the cell level:

Available sub-band for assignment (specified as a grouping scheme)

Demand (required number of TRXs)
Power offset (including power control)
Hopping mode
Assignment mode (group constrained or free)
Quality target (required C/I threshold)

4.3.5.1

Examples

4.3.5.1.1

Normal Cell Configuration

Contains 2 TRGs:

4.3.5.1.2

Concentric Cell Configuration

4.4

BCCH_trg:Requires a demand of 1 TRX and a high quality target.

TCH_trg:Requires a demand of N TRXs and allows a lower quality target.

BCCH_trg:Requires a demand of 1 TRX and a high quality target.

TCH_Outer_trg:Dedicated to the TCH for underlying layer.
TCH_Inner_trg:Dedicated to the TCH for the overlay layer specifying a reduced power for each member of this set
of TRXs.

Various Roles of Grouping Schemes

A grouping scheme appears in more than one place and has more than one role. This chapter is aimed at clarifying its
important role.
The facts are:

Each TRG has its grouping scheme.

Each IAssignmentPlan has a dynamic grouping scheme.

The manner in which these grouping schemes are used depends on the assignment mode and the hopping mode of the
TRG. The grouping scheme of each TRG supplies domain constraints, which, obviously, differ according to different
RESOURCE_TYPEs. The domain is always the union of all groups in the grouping scheme.
When the hopping mode of the TRG is set to SFH, the IAssignmentPlan interface assigns resources, which are group
numbers of the IAssignmentPlan.GetMALScheme() and not ARFCNs. The AFP is supposed to have created these groups
before assigning them.
If the TRG assignment mode is GROUP_CONSTRAINT and hopping mode is SFH, then the AFP must try to assign groups
according to the groups in the TRG grouping scheme.
If the TRG assignment mode is GROUP_CONSTRAINT and hopping mode is not SFH then the AFP must try to assign all
ARFCNs form a single group of the TRG grouping scheme.

4.5

Data Exchange

4.5.1

Nested Interfaces and Arrays as Means

As the AFP API conforms to COM interface, it does not pass complex data in structures or objects. Atoll can pass/
receive only a pre-defined and limited set of simple types (char, int, float, ) to/from the AFP. In order to transfer complex
data structures, one must pass nested interfaces. For example, Atoll passes a pointer of an IAfpNetworkData interface to
the AFP. The AFP can pass it an index, of a COM supported type, and receive an ITrg interface pointer. The ITrg interface
supplies all simple data elements corresponding to a TRX-group (TRG). An ITrg Interface can supply an IFrequencyBand, etc.
The only exceptions to this design are arrays of simple types (usually, arrays of ints), which are passed in the form of pointers. In this case, the size of the array is passed as well.
More explicitly, we allocate memory for N elements on one side of the interface and request the other side pass the
elements and put them in the memory space allocated. In some cases we may want to know how many elements were
actually put in the memory. This will require an additional parameter. In other cases we assume that before the elements
are requested, a function returns the actual number of elements so that the same number of elements is requested.
The table below presents all the interfaces in the AFPI and depicts their nesting hierarchy:

180

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

Implemented in Atoll

Implemented in the AFP

XIAfpNetworkData
XIAfpModel
XIPlanGenerator

XIAssignmentPlan

XIAFPConfigure (Optional)

XIRW_AssignmentPlan
XIDynamicGroupingScheme
XITrg
XIGroupingScheme
XIFrequencyBand
X(IQualityModel)
XIRadioTransmitter2
XItrgSeparations
XIInterfMatrix
XIAFPProgress

4.5.2

Elements Implemented by Atoll

4.5.2.1

IAfpNetworkData Interface
This interface bundles together all AFP relevant network information. The network information of each TRG (number of
channels, hopping mode, etc.) is packed together through the ITrg interface. The IAfpNetwork gives an array-like access
to all the ITrg instances of the network. In addition, it delivers two other interfaces, ItrgSeparation and IIInterfMatrix. ITrgSeparation handles the separation requirements between TRGs and the current assignment plan, while IIInterfMatrix gives
access to interference information.

4.5.2.2

IAssignmentPlan Interface
Read access to a Frequency, HSN, MAIO or BSIC plan. A plan is a match of resources to TRXs in a TRG.

4.5.2.3

IRW_AssignmentPlan:IAssignmentPlan Interface
Read and write access to a Frequency, HSN, MAIO or BSIC plan.

4.5.2.4

IGroupingScheme Interface
Read access to groups of resources (RGs) and to groups of RGs (lists of groups of resources).

4.5.2.5

IDynamicGroupingScheme:IGroupingScheme Interface
Read/Write access to groups of resources (RGs) and to groups of RGs.

4.5.2.6

ITrg Interface
Access to TRG and TRX properties.

4.5.2.7

IFrequencyBand Interface
Some AFP related parameters that can vary from one frequency band to another or from one TDMA technology to another.

4.5.2.8

ITrgSeparations Interface
Gives access to the separation constraints due to various reasons (co-site, co-cell, interference, ).

4.5.2.9

IInterfMatrix Interface
Provides access to Atoll interference calculations. It supports the simple interference models, where one or two numbers
weigh the interference between two TRGs. Moreover, it supports more complex interference models by providing access
to a cumulative density function of interference probabilities between pairs of TRGs.

Forsk 2007

AT260_DRG_E0

181

Developer Reference Guide

4.5.2.10

IAFPProgress Interface
Provides the AFP a means to report messages and check whether it has permission to continue its execution. IAFPProgress must not be used if the AFP opens a dialog of its own. AFP can choose to display messages in a simple manner
or to put information warnings and errors in Atolls event observer.

4.5.3

Elements Implemented by The Model

4.5.3.1

IAfpModel Interface
Generates an IPlanGenerator instance. Each instance can be paused and reactivated while keeping internal state data.

4.5.3.2

IPlanGenerator Interface
Looks for a good frequency plan.

4.5.3.3

IAFPConfigure Interface (Optional)

If the AFP does not implement IAFPConfigure it will be provided with an AFP_BASE_CONFIG structure containing default
configuration information. Through the COM mechanism of query interface, Atoll will know whether the AFP component
implements IAFPConfigure or not. If it does, Atoll will call the function IAFPConfigure::Configure(wind), which will permit
the AFP component to present its own configuration dialog in the window pointed to by wind.

4.6

Reference Guide

4.6.1

Enumerations and Structures

The following table describes the enumerations and structures used in the Interface.

4.6.1.1

ALLOCATION_TYPE

a.

4.6.1.2

4.6.1.3

182

Constant

Value

Description

CHANNEL_ALLOC

0x1

Channels.

HSN_ALLOC

0x2

Hopping Sequence Number.

MAIO_ALLOC

0x8

Mobile Allocation Index Offset.

BSIC_ALLOC

0x10

Base Station Identifier Code.

MAL_ALLOCa

0x20

Mobile Allocation List.

CODE_ALLOC

0x40

Not used.

If MAL_ALLOC is not masked, SFH Trgs would be considered Frozen.

ALLOCATION_OPTIONS (Not Used)

Constant

Value

Description

QUALITY_TARGET

0x1

Not to improve TRGs already compliant with their quality target.

COMPUTE_SEPARATION

0x2

Use the TRG and interference information to compute a compatibility

matrix. Then create an allocation compliant with this matrix.

OPTIMIZE_INTEREFERENCE

0x4

Minimize interference.

ADVANCED_CI_ESTIMATION

0x8

Advanced quality estimation by combination of C/I histograms.

Description

RESOURCE_TYPE
Constant

Value

CHANNEL_TYPE

HSN_TYPE

MAIO_TYPE

BSIC_TYPE

CODE_TYPE

AT260_DRG_E0

Not used.

Forsk 2007

Chapter 4: Basic AFP API

4.6.1.4

ASSIGNMENT_MODE

a.

4.6.1.5

4.6.1.5.1

Constant

Value

Description

FREE_ASSIGNENTa

Resource number can be assigned without grouping consideration,

but still with restriction to BAND or SUB-BAND limitations.

GROUP_ASSIGNENT4

Resource numbers, which may be assigned to a cell, must belong to

the same resource group whenever possible.

Please note and respect the intentional ASIGNENT instead of ASSIGNMENT.

ASSIGNMENT_STATE
Constant

Value

Description

TO_ASSIGN

0x1

TRG ready to be assigned. (See section 4.6.1.5.1 for more details)

FROZEN

0x2

TRG frozen. (See section 4.6.1.5.1 for more details)

MODIFIED

0x4

TRG has been modified in at least one of the IRW_AssignmentPlan

clone objects.

CREATED

0x8

TRX created by the AFP.

TO_ASSIGN and FROZEN States

The AFP API allows independent access to TO_ASSIGN, meaning that the subcell is in the AFP scope, and FROZEN.
Each combination of the two has a differnt meaning as explained below.
Let S(i) define a TRG i "Selected for AFP". S(i) = True, if and only if:

TRG i is inside the filtering polygon (blue), if one exists.

TRG i is inside the calculation zone (red), if one exists.
TRG i is inside the focus zone (green), if one exists.
TRG i passes all filtering at the main Transmitters folder.
TRG i belongs to the subfolder (or to the transmitter) for which the AFP was launched.

Let F(i) define a TRG i "Frozen for AFP". F(i) = True, if and only if:

TRG i is inside a cell whose Channel and MAIO are frozen at cell level.
TRG i belongs to a TRX type that was frozen by the AFP launch wizard.

When the following method of the AFP API is called:

GetAssignmentState(rtype /* =CHANNEL_TYPE */, trg /* =i */, trxNumber /* = -1

*/, &ass_state);
The ass_state varible may contain the following values depending on different cases:

Case

Current Approach

Previous Approach
(Atoll 2.4.1 and earlier)

S(i) == True AND F(i) == True

TO_ASSIGN | FROZEN

FROZEN

S(i) == True AND F(i) == False

TO_ASSIGN

TO_ASSIGN

S(i) == False AND F(i) == True

FROZEN

FROZEN

S(i) == False AND F(i) == False

FROZEN

FROZEN

In the case of other resource types, or in the case of (trxNumber != -1), F(i) changes but S(i) remains the same. Thus the
above table remains the same too.

4.6.1.6

4.6.1.7

Forsk 2007

HOPPING_MODE
Constant

Value

Description

NONE_FH

No Frequency Hopping.

BFH

BaseBand Frequency Hopping.

SFH

Synthesized Frequency Hopping.

Constant

Value

Description

COSITE

0x1

AFP_RELATION_TYPE

COCELL

0x2

NEIGHBOUR

0x4

SYNCHRO

0x8

AT260_DRG_E0

Synchronised TRXs for MAIO management.

183

Developer Reference Guide

SPECIAL

4.6.1.8

0x10

User defined special relations.

QUALITY_METRIC (Not Used)

Default Value: CI

4.6.1.9

Constant

Value

Description

CI

Interference.

RBER

Bit Error Rate.

FER

Frame Error Rate.

BLER

Block Error Rate.

MOS

Mean option score (value 5 = EXCELLENT, 0 = BAD).

USER_DEFINED

User defined.

AFP_BASE_CONFIG
Structure containing default configuration information.

Members

Type

Description

duration

long

Maximum duration in seconds (no limit = -1).

options

int

Not used yet.

allocType

int

Mask of ALLOC_TYPE.

keepPrev

boolean

Not used yet.

keepFrozen

boolean

Not used yet.

quickEvaluation

boolean

Not used yet.

seed

int

Not used yet.

4.6.2

Interfaces Implemented by Atoll

4.6.2.1

IAfpNetworkData Interface
This interface bundles together all AFP relevant network information. The network information of each TRG (number of
channels, hopping mode, etc.) is packed together through the ITrg Interface. The IAfpNetworkData gives an array-like
access to all the ITrg instances of the network. In addition it delivers the separation access and the interference access
interfaces.

4.6.2.1.1

IAfpNetworkData::GetTRGCount Method
Returns the number of TRX groups (TRG).

HRESULT

GetTRGCount ([out] int *count)

Parameters
count:

Number of TRGs.

Return Values
S_OK. (count NULL is not supported)

4.6.2.1.2

IAfpNetworkData::GetFirstTRG Method
Returns the index of the first TRG of the transmitter.

HRESULT

GetFirstTRG ([in] IRadioTransmitter2*

t, [out] int* firstTrgIndex)

Parameters
t:

Pointer of the transmitter.

firstTRGIndex:

Index of the first TRG.

Return Values
E_POINTER, if t or firstTrgIndex is NULL.
S_OK, if there is a TRG for the transmitter in the array,
Else S_FALSE.

184

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

4.6.2.1.3

IAfpNetworkData::GetTRG Method
Returns the TRG interface for one TRX group. TRGs are sorted by site and sector.

HRESULT

GetTRG ([in] int indx, [out] ITrg** trg)

Parameters
index:

Index of the TRG.

trg:

Pointer of the ITrg associated interface.

Return Values
E_POINTER, if trg is NULL.
S_OK, if index corresponds to a TRG in the array,
Else S_INVALIDARG.

4.6.2.1.4

IAfpNetworkData::GetSeparations Method
Provides access to separations between TRG.

HRESULT

GetSeparations ([in] RESOURCE_TYPE res,,[out] ITrgSeparations** sep)

Parameters
res:

Resource type of TRG.

sep:

Pointer of the ITrgSeparations associated interface.

Return Values
S_OK.
E_POINTER, if sep is NULL.
res is currently not used, CHANNEL_TYPE is assumed.

4.6.2.1.5

IAfpNetworkData::GetCurrentPlan Method
Provides the current plan.

HRESULT

GetCurrentPlan ([out] IAssignmentPlan** plan)

Parameters
plan:

Pointer of IAssignmentPlan interfaces current plan.

Return Values
S_OK.
E_POINTER, if plan is NULL.

4.6.2.2

IAssignmentPlan Interface
Through this Interface, the AFP can access a frequency plan, a MAIO plan, an HSN plan, a BSIC plan or a scrambling
code plan. The RESOURCE_TYPE enum determines the type of plan being accessed.
An assignment plan matches resources to TRGs or TRXs. A TRX is identified by its TRG and by its TRX-Number in the
TRG. The TRX-Number is an id-space that can help the user in identifying TRXs. A TRX may have a special assignment
state (Frozen), a frequency or a list of frequencies, a MAIO etc. Different IAssignmentPlan instances can hold different
assigned values for the same TRX (Its assignment state, Frozen or not, is supplied by the ITrg interface and does not
change).
Notes:

4.6.2.2.1

The AFP will hold a few IAssignmentPlan interfaces, one for the existing plan, one for the best and a few
others (if exist). All the IAssignmentPlan interfaces are obtained from each other by the GetClone()
function, which supplies a virtual editable copy. This is the AFP output in the end.

IAssignmentPlan::GetResource Method
Provides access to a resource number at TRX or TRG level.

HRESULT GetResource([in] RESOURCE_TYPE type,[in] int trgIndx,[in] int trxNumber, [out] int *res);

Forsk 2007

AT260_DRG_E0

185

Developer Reference Guide

Parameters
type:

Resource type.

trgIndx:

Index of the TRG.

trxNumber:
level.

Number of the TRX in the transmitter. If trxNumber is 1, access is requested at TRG

res:

Number of the resource. If 1, the resource is unassigned.

Return Values
E_POINTER, if res is NULL.
S_OK, if res is not 1,
Else S_FALSE.

Remarks
If the Hopping mode of the TRG is SFH and the resource type is FREQUENCY_TYPE then res is the group number of the
MAL Grouping Scheme (see 4.6.2.2.7 IAssignmentPlan.GetMalScheme()). In all other cases, res is the resource number
(ARFCN, HSN, MAIO, BSIC, etc.).

4.6.2.2.2

IAssignmentPlan::GetTrxCount Method
Provides access to the TRX count of a TRG.

HRESULT GetTrxCount([in] int trgIndx,[out] short* trxCount);

Parameters
trgIndx:

Index of the TRG.

trxCount:

Count of TRX in the TRG.

Return Values
E_POINTER, if trxCount is NULL.
S_OK or E_INVALIDARG, if trgIndx is past the end of the array or is < 0.

4.6.2.2.3

IAssignmentPlan::GetTrxNumber Method
Provides access to the TRX number of a TRX from its index.

HRESULT GetTrxNumber([in] int trgIndx,[in] short trxIndx,[out] int* trxNumber);

Parameters
trgIndx:

Index of the TRG.

trxIndx:

Index of the TRX in the TRG.

trxNumber:

Number of the TRX at index trxIndx in the TRG

Return Values
E_POINTER, if trxNumber is NULL.
S_OK or E_INVALIDARG, if trgIndx is past the end of the array or is < 0.
E_FAIL, if *trxNumber < 0.

4.6.2.2.4

IAssignmentPlan::GetTrxIndex Method
Provides access to the TRX index of a TRX from its number.

HRESULT GetTrxIndex([in]

int trgIndx,[in] int trxNumber,[out] short* trxIndx);

Parameters
trgIndx:

Index of the TRG.

trxNumber:

Number of the TRX.

trxIndx:

Index of the TRX in the TRG.

Return Values
E_POINTER, if trxIndx is NULL.
S_OK or E_ INVALIDARG, if trgIndx is past the end of the array or is < 0.

186

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

E_FAIL, if *trxIndx < 0.

4.6.2.2.5

IAssignmentPlan::GetTrxNumbers Method
Provides access in a single step to all the TRX numbers of a TRX from the index of the TRG.

HRESULT GetTrxNumbers([in] int trgIndx, [in] short count, [out,size_is(count)]

int* trxNumbers);
Parameters
trgIndx:

Index of the TRG.

count:

Count of numbers to get from the call.

trxNumbers:

Numbers of the TRX.

Return Values
E_POINTER, if trxNumbers is NULL.
S_OK or S_FALSE, if one of the TRX numbers is 1.

4.6.2.2.6

IAssignmentPlan::CreateClone Method
Creates a read/write clone based on the current assignment plan.

HRESULT CreateClone([out] IRW_AssignmentPlan** clone);

Parameters
clone:

The new read-write assignment plan.

Return Values
S_OK.
E_POINTER, if clone is NULL.

4.6.2.2.7

IAssignmentPlan::GetMALScheme Method
Returns a dynamic grouping scheme. You must create new groups in this scheme and fill them up with frequencies. You
can then assign these groups to the SFH TRXs.

HRESULT GetMALScheme([out] IDynamicGroupingScheme** scheme);

Parameters
scheme:

The dynamic grouping scheme.

Return Values
S_OK.
E_POINTER, if scheme is NULL.

4.6.2.2.8

IAssignmentPlan::GetAssignmentState Method
Gets assignment state of TRG or TRX.

HRESULT GetAssignmentState([in] RESOURCE_TYPE type, [in]

int
trxNumber, [out] ASSIGNMENT_STATE* state);

int

trgIndx, [in]

Parameters
type:

The resource type.

trgIndx:

The index of the requested TRG.

trxNumber:
at TRG level.

The number of the requested TRX in the TRG. If trxNumber is 1, the request is done

state:

Requested assignment state.

Notes:

See section 4.6.1.5.1 for more details on the TO_ASSIGN and FROZEN assignment states.

Return Values
S_OK.

Forsk 2007

AT260_DRG_E0

187

Developer Reference Guide

E_POINTER, if state is NULL.

4.6.2.3

IRW_AssignmentPlan:IAssignmentPlan Interface
Read and write access to a Frequency, HSN, MAIO or BSIC plan. By inheriting from IAssignmentPlan it already includes
all read access. Next sections describe the additional write abilities:

4.6.2.3.1

IRW_AssignmentPlan::AddTrxs Method
Adds new TRX numbers to a TRG.

HRESULT AddTrxs([in] int trgIndx, [in] short newTrxCount, [out, size_is(newTrxCount)] int* newTrxNumbers);
Parameters
trgIndx:

Index of the TRG.

newTrxCount:

Count is the new count of TRX to create in the TRG.

newTrxNumbers:

Numbers of the new TRX.

Return Values
S_OK.
E_POINTER, if newTrxNumber is NULL.
E_INVALIDARG, in case trgIndx is incorrect.
(newTrxNumber is supposed to be allocated at newTrxCount)

4.6.2.3.2

IRW_AssignmentPlan::RemoveTrx Method
Removes a TRX from a TRG by its number.

HRESULT RemoveTrx([in] int trgIndx,[in] int trxNumber);

Parameters
trgIndx:

Index of the TRG.

trxNumber:

Index of the TRX to remove.

Return Values
S_OK.
E_INVALIDARG, in case trgIndx is incorrect.

4.6.2.3.3

IRW_AssignmentPlan::SetResource Method
Writes a resource number.

HRESULT SetResource([in] RESOURCE_TYPE type, [in] int

Number, [in] int res);

trgIndx, [in] int

trx-

Parameters
type:

Resource type.

trgIndx:

Index of the TRG.

trxNumber:

Index of the TRX. If trxNumber is 1, the request is done at TRG level.

res:

Resource value.

Return Values
S_OK.
E_INVALIDARG, in case trgIndx is incorrect.

4.6.2.4

IGroupingScheme Interface
This interface provides read access to groups of resources (RGs) and groups of RGs. Two ID spaces are treated by this
interface: The group Ids, which span a set of groups and the resource Ids, which span a set of resources in a group.
The resources themselves are just simple numbers, which can stand for channel numbers, HSNs, MAIOs or others.

4.6.2.4.1

IGroupingScheme::GetGroupingSchemeID Method
Gets the unique identifier of a grouping scheme.

188

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

HRESULT GetGroupingSchemeID([out] VARIANT *id);

Parameters
id:

Id of the grouping scheme.

Return Values
S_OK.
E_POINTER, if id is NULL.

4.6.2.4.2

IGroupingScheme::GetGroupCount Method
Gets the number of groups composing the scheme.

HRESULT GetGroupCount([out] int *count);

Parameters
count:

Count of groups composing the grouping scheme.

Return Values
S_OK.
(count = NULL is not supported)

4.6.2.4.3

IGroupingScheme::GetGroupSize Method
Gets the size of a group in the grouping scheme.

HRESULT GetGroupSize ( [in]

int grpIndx,

// index of group

[out] int *size);

Parameters
grpIndx:

Index of the group in the grouping scheme.

size:

Size of the group in the grouping scheme.

Return Values
S_OK or E_INVALIDARG.
(size = NULL is not supported)

4.6.2.4.4

IGroupingScheme::GetResourceNumbers Method
Gets the resource numbers of a group in the grouping scheme.

HRESULT
GetResourceNumbers([in]
[out,size_is(count)] int *numbers);

int

grpIndx,

[in]

int

count,

Parameters
grpIndx:

Index of the group in the grouping scheme.

count:

Count of elements in the group.

numbers:

Numbers of the elements in the group.

Return Values
S_OK or E_INVALIDARG.
(numbers = NULL is not supported)
Checks that count is exactly the group size.

4.6.2.4.5

IGroupingScheme::Contains Method
Searches whether a given number belongs to a given group.

HRESULT Contains([in]

int grpIndx, [in]

int r);

Parameters

Forsk 2007

grpIndx:

Index of the group in the grouping scheme.

r:

Numbers of the element to search in the group.

AT260_DRG_E0

189

Developer Reference Guide

Return Values
S_OK, if the resource belongs to the group, otherwise S_FALSE.
E_INVALIDARG, if grpIndx is incorrect.

4.6.2.5

IDynamicGroupingScheme: IGroupingScheme Interface

This interface provides read/write access to groups of resources (RGs) and to groups of RGs. It adds three additional
methods to base interface IGroupingScheme.

4.6.2.5.1

IDynamicGroupingScheme::AddGrp Method
Creates a new group in the dynamic grouping scheme.

HRESULT AddGrp([in] int grpSz, [out] int* grpIndx);

Parameters
grpSz:

Size of the new group.

grpIndx:

Index where the new group has been added.

Return Values
S_OK.
(grpIndx = NULL is not supported)

4.6.2.5.2

IDynamicGroupingScheme::SetGrp Method
Sets the elements of a group in the dynamic grouping scheme.

HRESULT SetGrp([in] int grpIndx, [in] int grpSz, [in, size_is(grpSz)] int *numbers);
Parameters
grpIndx:

Index of the group in the dynamic grouping scheme.

grpSz:

Size of the group.

numbers:

Array of numbers to set in the group.

Return Values
S_OK.
E_INVALIDARG,if there is a problem with grpIndx or grpSz.
(numbers = NULL is not supported)

4.6.2.5.3

IDynamicGroupingScheme::DeleteGrp Method
Deletes a group from the dynamic grouping scheme.

HRESULT DeleteGrp([in] int grpIndx);

Parameters
grpIndx:

Index of the group to delete from the dynamic grouping scheme.

Return Values
S_OK.
E_INVALIDARG, if there is a problem with grpIndx.
Caution:

4.6.2.6

AFP model must delete groups that are no longer assigned in RW_IAssignmentPlan clone to free memory.

ITrg Interface
Provides access to TRG and TRX properties.

4.6.2.6.1

ITrg::GetIndx Method
Gets the index of the TRG (TRX-group) in the IAfPNetworkData.

HRESULT GetIndx([out] int *indx);

190

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

Parameters
indx:

Index of the TRG.

Return Values
S_OK.
(indx = NULL is not supported)

4.6.2.6.2

ITrg::GetTrxType Method
Gets the TRX type of the TRG. By extension, this type is also called the TRG type.

HRESULT GetTrxType([out] BSTR* trxType);

Parameters
trxType:

The TRX type of the TRG (BCCH, TCH , TCH_INNER, etc).

Return Values
S_OK.
(trxType = NULL is not supported)

4.6.2.6.3

ITrg::ContainsBroadcastChannel Method
Gets the TRX type of the TRG. By extension, this type is also called the TRG type.

HRESULT ContainsBroadcastChannel();
Parameters
None.

Return Values
S_OK, if the TRG contains a (the) broadcast channel,
Else S_FALSE.

4.6.2.6.4

ITrg::GetGroupingScheme Method
Gets the grouping scheme of a given resource type.

HRESULT GetGroupingScheme( [in]

gs);

RESOURCE_TYPE type, [out] IGroupingScheme**

Parameters
type:

Type of the resource.

gs:

Grouping scheme of the resource.

Return Values
E_POINTER, if gs is NULL.
S_OK, if the resource type is supported,
Else E_INVALIDARG.
Currently, the only supported resource types are HSN_TYPE, BSIC_TYPE and CHANNEL_TYPE.

4.6.2.6.5

ITrg::GetFrequencyBand Method
Gets the frequency band of the TRG.

HRESULT GetFrequencyBand([out] IFrequencyBand** fb);

Parameters
fb:

Pointer of the frequency band of the TRG.

Return Values
S_OK.
E_POINTER, if fb is NULL.

Forsk 2007

AT260_DRG_E0

191

Developer Reference Guide

4.6.2.6.6

ITrg::GetDemand Method
Gets the demand relative to the resource type.

HRESULT GetDemand( [in]

RESOURCE_TYPE type, [out] int* demand);

Parameters
type:

Resource type.

demand:

Number of required resource in the TRG.

Return Values
S_OK, for supported types.
E_POINTER, if demand is NULL.
Currently, supported types are HSN_TYPE, BSIC_TYPE, CHANNEL_TYPE and MAIO type.

4.6.2.6.7

ITrg::GetTrafficLoad Method
Gets the traffic load of a TRG. It is the number of Erlangs per Time Slot. In the future versions, it will incorporate data and
signalisation traffic as well but will still be defined in units parallel to Erlangs per Time Slot.

HRESULT GetTrafficLoad([out] float* traffic);

Parameters
traffic:

Traffic load.

Return Values
S_OK.
E_POINTER, if traffic is NULL.

4.6.2.6.8

ITrg::GetDLTimeSlotUseRatio Method
Gets the downlink time slot's exploitation ratio, which inludes the effect of DTX.

HRESULT GetDLTimeSlotUseRatio([out] float* tsExp);

Parameters
tsExp:

Downlink time slot's exploitation ratio.

Return Values
S_OK.
(tsExp = NULL is not supported)

Remarks
When DTX or AMR-HR are used, the downlink part of the communication does not always use 100% of the bursts in its
time slot. The averaging refers to the different communications in the TRG. Typical values are:

4.6.2.6.9

TCH with no DTX and no AMR-HR 1

TCH with DTX 0.7
TCH with DTX and AMR-HR 0.65

ITrg::GetCostWeightingFactor Method
Gets the cost of the weighting factor.

HRESULT GetCostWeightingFactor([out] float* factor);

Parameters
factor:

Weighting of the TRG in the frequency assignment process.

Return Values
S_OK.
(factor = NULL is not supported)

4.6.2.6.10

ITrg::GetHoppingMode Method
Gets the frequency hopping mode of the TRG.

192

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

HRESULT GetHoppingMode([out] HOPPING_MODE,* mode);

Parameters
mode:

Frequency hopping mode.

Return Values
S_OK.
E_POINTER, if mode is NULL.

4.6.2.6.11

ITrg::GetAssignmentMode Method
Gets the assignment mode of the TRG.

HRESULT GetAssignmentMode ([out] ASSIGNMENT_MODE* mode);

Parameters
mode:

Assignment mode.

Return Values
S_OK.
E_POINTER, if mode is NULL.

4.6.2.6.12

ITrg::GetMALSize Method
Gets the maximum permitted MAL size (relevant only in case of SFH).

HRESULT GetMALSize([out] int* sz);

Parameters
sz:

Maximum MAL size.

Return Values
S_OK.
E_POINTER, if sz is NULL.

4.6.2.6.13

ITrg::IsInRelation Method
Evaluates a type of relation between the current TRG and another one.

HRESULT IsInRelation( [in] AFP_RELATION_TYPE type, [in] int trgIndx);

Parameters
type:

Type of relation evaluated.

trgIndx:

Index of the TRGs with which the relation with the current TRG must be evaluated.

Return Values
S_OK, if the TRG fulfils the supported tested relation,
Else S_FALSE.
E_FAIL, for an unsupported relation type.
Currently, the only supported AFP_RELATION_TYPE for this method are COCELL, COSITE, NEIGHBOUR and
SYNCHRO.

4.6.2.6.14

ITrg::GetTrgRelationCount Method
Counts a type of relation between the current TRG and others.

HRESULT GetTrgRelationCount( [in] AFP_RELATION_TYPE type, [out] int* count);

Parameters

Forsk 2007

type:

Type of relation evaluated.

count:

Count of relations of type type for the current TRG.

AT260_DRG_E0

193

Developer Reference Guide

Return Values
E_POINTER, if count is NULL.
S_OK, if type is a supported relation type.
E_FAIL, for an unsupported relation type.
Currently, the only supported AFP_RELATION_TYPE for this method are COCELL, COSITE, NEIGHBOUR and
SYNCHRO.

4.6.2.6.15

ITrg::GetTrgRelation Method
Gets the TRG indexes of the TRG having a relation of a certain type with the current TRG.

HRESULT GetTrgRelation( [in] AFP_RELATION_TYPE type, [in] int count, [out,

size_is(count)] int* trgIndexes);
Parameters
type:

Type of relation evaluated.

count:

Count of relations of type type for the current TRG.

trgIndexes:

Indexes of the TRGs having this type of relation with the current one.

Return Values
E_POINTER, if trgIndexes is NULL.
S_OK, if type is a supported relation type.
E_FAIL, for an unsupported relation type.
Currently, the only supported AFP_RELATION_TYPE for this method are COCELL, COSITE, NEIGHBOUR and
SYNCHRO.

4.6.2.6.16

ITrg::GetTransmitter Method
Gets the transmitter to which belong the TRG.

HRESULT GetTransmitter([out] IRadioTransmitter2** tr);

Parameters
tr:

Transmitter.

Return Values
S_OK.
E_POINTER, if tr is NULL.

4.6.2.6.17

ITrg::GetQualityThreshold Method
Gets the quality characteristics, i.e. metric and threshold.

HRESULT GetQualityThreshold([out] QUALITY_METRIC *metric, [out] float* qmin);

Parameters
metric:

Quality metric used.

qmin:

Minimum quality threshold. Its actual value and unit depend on the metric.

Return Values
S_OK.
E_POINTER, if metric or qmin is NULL.
Currently, the only supported metric is CI (metric parameter is not used at all) and qmin is a CI threshold in dB.

4.6.2.6.18

ITrg::GetProbabilityThreshold Method
Gets the value of minProba. Quality at this TRG is acceptable if and only if the probability that a communication has acceptable quality (as defined above) is greater than minProba.

HRESULT GetProbabilityThreshold([out] float* minProba);

Parameters
minProba:

194

Minimum acceptable probability.

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

Return Values
S_OK.
E_POINTER, if minProba is NULL.

4.6.2.7

IFrequencyBand Interface
Models the frequency bands at the AFP level.

4.6.2.7.1

IFrequencyBand::GetMultiPlexingFactor Method
Gets the number of time slots on a physical carrier.

HRESULT GetMultiPlexingFactor([out] int* factor);

Parameters
factor:
systems, etc).

Number of time slots on a physical carrier (e.g. 8 for GSM, 3 for some other TDMA

Return Values
S_OK.
E_POINTER, if factor is NULL.

4.6.2.7.2

IFrequencyBand::GetCoherenceBandWidth Method
Gets coherence bandwidth (in channels).

HRESULT GetCoherenceBandWidth([out] int* widthInChannels);

Parameters
widthInChannels:

Bandwidth in the channels of the coherence band.

Return Values
S_OK.
E_POINTER, if widthInChannels is NULL.

4.6.2.7.3

IFrequencyBand::GetAdjascentSuppression6 Method
Gets the adjacent suppression level for the nth adjacency level.

HRESULT GetAdjascentSuppression ([in] int n, [out]float *asupp);

Parameters
n:

Adjacency level.

asupp:

Suppression value in dB.

Return Values
E_POINTER, if asupp is NULL.
S_OK, if asked for a supported level,
Else E_NOTIMPL.
Currently, levels 0, 1 and 2 are supported.

4.6.2.8

ITrgSeparations Interface
Gives access to the separation constraints due to various reasons (co-site, co-cell, interference, ).

4.6.2.8.1

ITrgSeparations::GetSeparation Method
Gets matrix-like access to separation relations.

HRESULT GetSeparation( [in] int type, [in] int trg1, [in] int trg2, [out] int*
sep);

6.

Forsk 2007

Please note and respect the intentional ADJASCENT instead of ADJACENT.

AT260_DRG_E0

195

Developer Reference Guide

Parameters
type:

Combination of different AFP_RELATION_TYPE.

trg1:

Index of first TRG.

trg2:

Index of second TRG.

sep:
in type.

Maximum values of all the separations caused by the relation types asked for together

Return Values
S_OK.
E_POINTER, if sep is NULL.
E_FAIL, if there was a problem while loading the separations table.

4.6.2.8.2

ITrgSeparations::GetDefaultSeparation Method
No longer supported.
Gets optimized access to separation relations.

HRESULT GetDefaultSeparation( [in]

int type, [in]

int trg, [out] int* sep);

Parameters
type:

Combination of different AFP_RELATION_TYPE.

trg:

Index of TRG.

sep:
in type.

Maximum values of all the separations cause by the relation types asked for together

Return Values
E_POINTER, if sep is NULL.
S_OK, for the supported types.
E_FAIL, if there was a problem while loading the separations table.
E_NOTIMPL, for others.
Currently, the supported types are COSITE, COCELL, NEIGHBOUR and SPECIAL. Combination of types is not
supported. Pass a simple AFP_RELATION_TYPE instead.

4.6.2.8.3

ITrgSeparations::GetRelationsCount Method
Gets count of separation relations of a TRG.

HRESULT GetRelationsCount( [in] int type, [in] int trg, [out] int* count);
Parameters
type:

Combination of different AFP_RELATION_TYPE.

trg:

Index of TRG.

count:

Count of relations between selected TRG for given type.

Return Values
S_OK.
E_POINTER, if count is NULL.
E_FAIL, if there was a problem while loading the separations table.

4.6.2.8.4

ITrgSeparations::GetRelation Method
Gets a specific relation.

HRESULT GetRelation( [in] int type, [in] int trg1, [in] int indx, [out] int*
trg2, [out] int* sep);
Parameters

196

type:

Combination of different AFP_RELATION_TYPE.

trg1:

Index of TRG.

indx:

Index of the relation among all the relations defined for this TRG.

trg2:

TRG with which TRG1 is related.

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

sep:

Value of the separation for this relation.

Return Values
S_OK.
E_POINTER, if trg2 or sep is NULL.
E_FAIL, if there was a problem while loading the separations table.

4.6.2.9

IInterfMatrix Interface
Provides access to Atoll interference calculations and supports the simple interference models where one or two numbers
weigh the interference between two TRGs. Furthermore, it supports more complex interference models through providing
access to a cumulative density function of interference probabilities between pairs of TRGs.

4.6.2.9.1

IInterfMatrix::GetHistogramSize Method
Gets the histogram size for a given TRG.

HRESULT GetHistogramSize( [in] int trgv, [out] int* nThresh);

Parameters
trgv:

Index of the (victim) TRG.

nThresh:

Limit size of the histogram (irrespective of the interferer).

Return Values
S_OK.
E_POINTER, if nThresh is NULL.

4.6.2.9.2

IInterfMatrix::GetInterferingHistogram Method
Gets the histogram values for a TRG couple (victim, interferer).

HRESULT GetInterferingHistogram( [in] int trgv, [in] int trgi, [in] int maxCount, [out] int*
count, [out, size_is(maxCount)] float* thresholds, [out,
size_is(maxCount)] float* probas);
Parameters
trgv:

Index of the victim TRG.

trgi:

Index of the interferer TRG.

maxCount:

Size to which the following arrays are dimensioned.

count:

Actual size of the histogram.

thresholds:

C/I thresholds (in dB).

probas:
For the ith C/I value, probas[i] is the ratio of traffic below this value. More precisely,
probas[i] is the amount of traffic having better C/I conditions than thresholds[i] divided by total traffic.

Return Values
E_POINTER, if count or thresholds or probas is NULL.
S_OK.
S_FALSE, if trgv and trgi have the same value or (*count) > maxCount.

4.6.2.9.3

IInterfMatrix::GetInterferingProbability Method
Gets the interfering probability for a TRG couple (victim, interferer) and a given C/I threshold.

HRESULT GetInterferingProbability( [in] int trgv, [in] int trgi, [in] float
CI_threshold, [out] float* proba);
Parameters

Forsk 2007

trgv:

Index of the victim TRG.

trgi:

Index of the interferer TRG.

threshold:

C/I threshold (in dB).

proba:

Probability associated with the threshold.

AT260_DRG_E0

197

Developer Reference Guide

Return Values
S_OK.
E_POINTER, if proba is NULL.

4.6.2.9.4

IInterfMatrix::GetInterfererCount Method
Counts the interferer TRGs of a victim TRG.

HRESULT GetInterfererCount( [in] int trgv, [out] int* count);

Parameters
trgv:

Index of the victim TRG.

count:

Count of interferer TRGs.

Return Values
S_OK.
E_POINTER, if count is NULL.

4.6.2.9.5

IInterfMatrix::GetInterferers Method
Gets the interferer TRGs of a victim TRG.

HRESULT GetInterferers( [in] int trgv, [in] int count, [out,size_is(count)]

int* trgi);
Parameters
trgv:

Index of the victim TRG.

count:

Count of interferer TRGs.

trgi:

Array of interferer TRGs indexes.

Return Values
S_OK.
S_FALSE, if count is different from the actual count of interferers.
E_POINTER, if trgi is NULL.

4.6.2.9.6

IInterfMatrix::GetVictimCount Method
Counts the victim TRGs of an interfering TRG.

HRESULT GetVictimCount( [in] int trgi, [out] int* count);

Parameters
trgi:

Index of the interfering TRG.

count:

Count of victim TRGs.

Return Values
S_OK.
E_POINTER, if count is NULL.

4.6.2.9.7

IInterfMatrix::GetVictims Method
Gets the victims TRGs of an interfering TRG.

HRESULT GetVictims ( [in] int trgi, [in] int count, [out,size_is(count)] int*
trgv);
Parameters
trgi:

Index of the interfering TRG.

count:

Count of victim TRGs.

trgv:

Array of victim TRGs indexes.

Return Values
S_OK.

198

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

S_FALSE, if count is different from the actual count of victims.
E_POINTER, if trgv is NULL.

4.6.2.9.8

IInterfMatrix::GetInterfererHistogram Method
Get the TRG interfering histogram of a victim TRG.

HRESULT GetInterfererHistogram( [in] int trgv, [in] int indx, [out] int* trgi,
[in] int maxCount, [out] int* count, [out, size_is(maxCount)] float* thresholds, [out, size_is(maxCount)] float* probas);
Parameters
trgv:

Index of the victim TRG.

index:

Index in the array of interfering TRG.

trgi:

Index of the interfering TRG.

maxCount:

Maximum size of the histograms.

count:

Actual size of the histograms.

thresholds:

C/I thresholds (in dB).

probas:
For the ith C/I value, probas[i] is the ratio of traffic below this value. More precisely,
probas[i] is the amount of traffic having better C/I conditions than thresholds[i] divided by total traffic.

Return Values
S_OK.
S_FALSE, if trgv and trgi have the same value or (*count) > maxCount.
E_POINTER, if trgi or count or thresholds or probas is NULL.

4.6.2.10

IAFPProgress Interface
Provides the AFP model with a default means to report messages and check whether it has permission to continue its
execution. IAFPProgress cyclic reporting is not mandatory if the AFP opens a dialog of its own.

4.6.2.10.1

IAFPProgress::StartProgressReport Method
Opens default progress report dialog.

HRESULT StartProgressReport ();

Parameters
None.

Return Values
S_OK.

4.6.2.10.2

IAFPProgress::OnProgress Method
It is to be called periodically. If it returns S_FALSE, the AFP had been stopped by the user. In addition, it is used to report
the soft constraints cost (usually Interferences) and the number of broken hard constraints (usually separations), which
were violated by the current best assignment.

HRESULT OnProgress([in] float softCost, [in] int sepBreak);

Parameters
softCost:

Status of soft constraints optimization.

sepBreak:

Number of separation violations.

Return Values
S_OK, if the user did not interrupt the task,
S_FALSE otherwise.

4.6.2.10.3

IAFPProgress::Display Method
Appends the status string to the status message in the progress dialog.

HRESULT Display([in] LPCWSTR

Forsk 2007

status);

AT260_DRG_E0

199

Developer Reference Guide

Parameters
status:

String to add.

Return Values
S_OK.

4.6.2.10.4

IAFPProgress::DisplayLogInfo Method
Creates a new information entry in Atoll's events observer and appends it to the status message as well.

HRESULT DisplayLogInfo(LPCWSTR

infoMsg);

Parameters
infoMsg:

String to add.

Return Values
S_OK.

4.6.2.10.5

IAFPProgress::DisplayLogWarning Method
Creates a new warning entry in Atoll's events observer and appends it to the status message as well.

HRESULT DisplayLogWarning(LPCWSTR

warnMsg);

Parameters
warnMsg:

String to add.

Return Values
S_OK.

4.6.2.10.6

IAFPProgress::DisplayLogError Method
Creates a new error entry in Atoll's events observer and appends it to the status message as well.

HRESULT DisplayLogError(LPCWSTR

errMsg);

Parameters
errMsg:

String to add.

Return Values
S_OK.

4.6.3

Interfaces Implemented by The Model

4.6.3.1

IAfpModel Interface
This interface provides with a IPlanGenerator instance, generally result of an assignment.

4.6.3.1.1

IAfpModel::GetPlanGenerator Method
Returns the IPlanGenerator instance.

HRESULT GetPlanGenerator([out] IPlanGenerator** planGenerator);

Parameters
planGenerator:

Pointer to a IPlanGenerator

Return Values
S_OK.
(planGenerator = NULL is not supported)

4.6.3.2

IPlanGenerator Interface
The actual implementation of the AFP model.

200

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

4.6.3.2.1

IPlanGenerator::Run Method
Runs the AFP model to generate a new plan.

HRESULT Run( [in] IAfpNetworkData* netWorkData, [in] IInterfMatrix* iMatrix,

[in]
IAfpProgress* progress, [in]
AFP_BASE_CONFIG* config, [out]
IRW_AssignmentPlan** result);
Parameters
netWorkData:

Pointer of the data of the network.

iMatrix:

Pointer of the IInterfMatrix.

progress:

Pointer of the IafpProgress.

config:

Configuration.

result:

Result of the AFP process.

Return Values
S_OK.
E_FAIL in case of problem.
(No parameter can be NULL)

4.6.3.2.2

IPlanGenerator::Improve Method
Improves a previous plan to generate a new plan.

HRESULT Improve ( [in] IAfpNetworkData* netWorkData, [in] IInterfMatrix*iMatrix, [in] IAfpProgress*progress, [in] AFP_BASE_CONFIG* config, [in] IAssignmentPlan* previous, [out] IRW_AssignmentPlan** result);
Parameters
netWorkData:

Pointer of the data of the network.

iMatrix:

Pointer of the IInterfMatrix.

progress:

Pointer of the IafpProgress.

config:

Configuration.

previous:

Previous plan.

result:

Result of the AFP process.

Return Values
S_OK.
E_FAIL in case of problem.
(No parameter can be NULL)

4.6.3.3

IAfpConfigure Interface
If the AFP does not implement IAFPConfigure, it will be provided with an AFP_BASE_CONFIG structure containing default
configuration information. By using the COM mechanism of query interface, Atoll will know whether the AFP component
implements IAFPConfigure or not. If it does, Atoll will call the function IAFPConfigure::Configure(wind) which permits the
AFP component to present its own configuration dialog in the window pointed to by wind (Atoll provides this entry window
to the AFP so that the AFP will present its dialogue within Atoll).

4.6.3.3.1

IAfpConfigure::Configure Method
The model may manage a specific configuration dialog inside Atoll.

HRESULT Configure([in] HWND parent);

Parameters
parent:

HWND of the parent to which the model must relate its config dialog(s).

Return Values
S_OK.

Forsk 2007

AT260_DRG_E0

201

Developer Reference Guide

4.7

Using the AFP Interfaces

4.7.1

The Basic main() of an AFP

// EXAMPLE of implementation of Calculate function
// -------------------------------------------------------------------------MyAFP::run(
IAfpNetworkData*

netWorkData,

// provide access to network data

IInterfMatrix*

iMatrix,

// interfering probabilities

IAFPProgress*

progress,

// for cyclic reporting by Atoll

AFP_CONFIG*

config,

// from configuration

IRW_AssignmentPlan** result)

// result of assignment

{
// Check config to know what to do
//-------------------------------if((config->allocationType&CHANNEL_ALLOC) != config->allocationType )
return E_FAIL;

// this means that only CHANNEL_ALLOC is

// supported by MyAFP

// Retrieve initial assignment Plan

//---------------------------------IAssignmentPlan* initialPlan=0;
res= netWorkData->GetCurrentPlan(&initialPlan);
// Initiate the result with the initial plan
// ----------------------------------------initialPlan->CreateClone(result);

//result is created as a copy of

// initialPlan

// MyAFP progress report strategy: to rely on the standard one of Atoll

// -------------------------------------------------------------------progress->StartProgressReport();
// Main optimisation loop
// ---------------------float totalCost=0;
progress->DisplayMessage(Initialization);
do
{
if(progress->OnProgress(totalCost)==S_FALSE)
// duration elapsed?, user abort?
goto cleanup;
progress->DisplayMessage(New trial);
// change result
tryANewAssignment(netWorkData,iMatrix,initialPlan,*result, &totalCost);
progress->DisplayMessage();
} while !MyStatisfactionCriteria(totalCost,intialPlan,*result)
// is the plan OK?
cleanup:
// ------progress->DisplayMessage(Cleanup);
initialPlan->Release();

// Advice: prefer usage of

// smart pointers rather than

202

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

// manual cleanup
return res;
}
// -------------------------------------------------------------------------// In this example, functions in italic (tryANewAssignment, MyStatisfaction
// Criteria) are assumed to be functions of MyAFP
Optionally, the AFP can provide its own configuration dialog in order to select specific parameters, before the call for the
method Calculate. To do that, it just has to implement IAFPConfigure interface:

interface IAFPConfigure : IUnknown

// to be implemented by AFP if specific
{

// configuration is required
HRESULT Configure(

// open a dialog for configuration

[in] HWND parent);

// parent window from which AFP is called

}
If Atoll detects that this interface is supported (with standard COM QueryInterface method of IUnknown interface), it will
then enable a configuration button in the Atoll GUI and will call the Configure method when the button is pressed. The
parent window parameter is the window in which AFP can open its dialog.

4.7.2

Working with Network Data

IAfpNetworkData is the root interface allowing access to the useful entities of the network data including:

Cells (transmitters in Atoll)

TRG (group of TRXs of a cell)
Available grouping scheme (through ITrg interface)
Neighbourhood
Frequency bands
Current assignment plan (frequency plan, HSN plan,

// Example: function collecting all TRGs whose frequency can be assigned

// ---------------------------------------------------------------------static HRESULT collectTrgToAssign(IassignmentPlan* plan, IAfpNetworkData *networkData, std::vector<int> *toAssign)
{
int num_trg;
networkData ->GetTrgCount(&num_trg);
for(int itrg=0;itrg< num_trg; itrg++)
{
ITrg* p_trg=0;
networkData->GetTrg(itrg,&p_trg);
ASSIGNMENT_STATE state;
plan->GetAssignmentState(CHANNEL_TYPE,itrg,-1,&state);
// -1 for trxGroup level
if( (state & TO_ASSIGN) != 0)
toAssign->push_back(trg);

// add to collection

}
return S_OK;
}
Notes:

Forsk 2007

See section 4.6.1.5.1 for more details on the TO_ASSIGN and FROZEN assignment states.

AT260_DRG_E0

203

Developer Reference Guide

4.7.3

Access to TRGs
TRGs can be accessed by a contiguous index between 0 and the total number of TRX goups provided by the function
GetTrgCount of IAfpNetworkData interface.
TRGs are sorted by sites and by cell. Functions GetRelationCount and GetRelations provide access to TRGs indices
related to a given one.

// Example 1: function providing cell cost associated to a given trg index

// by adding individual costs of all TRGs of the associated cell
// -----------------------------------------------------------------------float GetCellCost(IAfpNetworkData *networkData, int trg)
{
int nbTrg;
ITrg* p_trg=0;
netWorkData->GetTrg(trg,&p_trg))

// Get pointer on ITrg interface

// Get Number of trgs on the same cell

// ----------------------------------int nbCoCellTrgs;
p_trg->GetRelationCount(CO_CELL,& nbCoCellTrgs);
// Get Trgs on the same cell
// ----------------------------------int* coCellTrgs =

new int[nbCoCellTrgs];

p_trg->GetRelations(CO_CELL, nbCoCellTrgs,coCellTrgs);
float cost = IndividualTrgCost(trg);

// initiate with trg

// Get other Trgs on the same cell

// ----------------------------------for(int t=0; t< nbCoCellTrgs; t++)

// collect trgs to assign

cost+= IndividualTrgCost(coCellTrgs[t]);

// other trgs of the same cell

// Clean up
// --------delete coCellTrgs;
p_trg->Release();

// avdice: prefer use of smart pointers

return cost;
}
// Remarks -----------------------------------------------------------------// function IndividualTrgCost, in this example, is assumed to be provided by AFP

4.7.4

Access to Separations Constraints

ITrgSeparations interface provides access to the required resource separations between two TRX-groups for a given
resource type. You should notice that provided separations are only the ones due to hardware constraints (cavity combiners) and/or the ones specified as engineering rules by user (co-site separations, co-cell separations, and so on). Calculated separations due to interferences are not provided here, as they are assumed to be calculated by the AFP.
The simplest method to involve this interface is to use the Matrix like access method providing separation for a given pair
of TRGs:

// Example1: a function providing channel separation between to TRGs

// ----------------------------------------------------------------void GetchannelSeparation(IAfpNetworkData *networkData, int trg1,int trg2, int
*sep)
{
ITrgSeparations* separations;
int allRelationTypes = COSITE|COCELL| NEIGHBOUR|SPECIAL;
networkData->GetSeparations(CHANNEL_TYPE,&separations);
// Get max separation among all relation types

204

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

separations-> GetSeparation(allRelationTypes, trg1, trg2, sep); // sep is retrieved

// Cleanup
separations->Release();
}
Other methods of this interface are provided for optimisation. Specially, when required to know the TRGs that required
separation with a given one, the other methods avoid the necessity of scanning all TRGs to find out the answer. This is
mainly useful for large networks.

// Example2: this function calculates the maximum

channel separation required

// by a given trg with all others trg

// -------------------------------------------------------------------------int GetMaxchannelSeparation(IAfpNetworkData *networkData, int trg)
{
ITrgSeparations* separations;
int allRelationTypes = COSITE|COCELL| NEIGHBOUR|SPECIAL;
networkData->GetSeparations(CHANNEL_TYPE,&separations);
int relationCount;
int maxSep=0;
separations->GetRelationCount(allRelationTypes,trg, &relationCount);
for(int rel=0;i<relationCount;++rel)
{
int targetTgr;
int sep;
separations-> GetRelation(allRelationTypes,trg,rel,&targetTgr,&sep);
if(sep>maxSep)
maxSep=sep;
}
// Cleanup
separations->Release();
return maxSep;
}

4.7.5

Access to Grouping Schemes

As said before, a grouping scheme is the list of groups of resource numbers available for assignment for a given TRG.
The interface IGroupingScheme provides the number of groups of the scheme and the list of resource numbers for each
group of the scheme.

// Example: this function finds the first resource group (frequency group here)
// index containing a given channel for a given TRG
// if the channel is found, the faction returns TRUE, FALSE otherwise
// -------------------------------------------------------------------------BOOL GetFrequencyGroupIndx(IAfpNetworkData
*groupIndx)

*net,

int

trg,int

channel,int

{
// Getting the scheme
// ------------------ITrg *p_trg;
IgroupingScheme *p_scheme;
net->GetTrg(trg, &p_trg);
P_trg->GetScheme(CHANNEL_TYPE,&p_scheme);
// Scanning groups

Forsk 2007

AT260_DRG_E0

205

Developer Reference Guide

// --------------*groupIndx = -1;
int groupCount;
p_scheme->GetGroupCount(&groupCount);
for(int grp=0;grp<groupCount;grp++)
{
HRESULT res =p_scheme->Contains(grp, );
If(res == S_OK)
{
*grpIndx=grp;
return TRUE;
}
}
return FALSE;
}
The interface IDynamicGroupingScheme is derived from IGroupingScheme and is used for the storage of MALs (channels
lists) of the TRGs with SFH having FREE_ASSIGNMENT mode. In this case, the MALs used are free and are all stored
in the temporary Dynamic group scheme provided by the function GetFreeMALScheme of the IAssignmentPlan interface.
See 4.7.7 Working with Several Assignment Plans for an example using dynamic scheme.

4.7.6

Working with Interference Matrices

The interface IInterfMatrix provides access to interference results for each couple of TRGs (the victim and the interferer).
Interference results are provided as a cumulative density function of the interfering probabilities of a TRG victim in the
following way:

4.7.6.1

Example
(victim trg = trgv, interferer trg = trgi)

Index

Threshold

Probability

Meaning

0.01

Probability of a user of a trx of trg being interfered by trgi, with a

C/I<0db is 1% (0.01).

0.0.5

Probability of a user of a trx of trg being interfered by trgi, with a

C/I<9db is 5% (0.05).

14

0.15

Probability of a user of a trx of trg being interfered by trgi, with a

C/I<14db is 15% (0.15).

Y = probability that C/I (trgi->trgv) < x dB.

Notice that the probability of C/I being between 9db and 14db in the example can be retrieved by Proba[2] Probas[1] =
10%.
The method GetHistogram provides these Thresholds and Probabilities for a given couple of TRGs.
The method GetInterferingProbability provides a simplified access to histograms, giving an interpolated probability for a
specified threshold value.
The methods GetInterfererCount, GetVictimCount, GetInterferers, GetVictims and GetInterfererHistogram provide an optimised access, avoiding the necessity to scan all TRGs. This optimised access is similar to the one provided for ITrgSeparations.

4.7.7

Working with Several Assignment Plans

The Interface IAssignmentPlan provides read access to resources assigned to each TRX of the network.
IRW_AssignmentPlan is an interface derived from IassignmentPlan, which provides additional write access (for AFP
assignment purpose).
The AFP is assumed to work in parallel with several assignment plans, at least the initial one (state of assignment before
launching AFP) and the current one (the one in which AFP registered all assignments). At the end of the process, the AFP
is assumed to provide an IAssignmentPlan pointer as the result, which can also be the current one in the simplest case.
The AFP can also use other instances of assignment plans (best plan, current plan, etc).

206

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

Committing the assignments provided by the AFP is assumed to be taken under charge by Atoll. The initial assignment
plan is provided as a read-only plan. To register its assignments, the AFP is assumed to create a new one using the
CreateClone method, which provides a write access plan (IRW_AssignmentPlan) based on the initial one.
Notes:

In order to minimize the storage space required, created clones keep a pointer on the original one used for
creation and only register modifications.

Important:

If B is an assignment plan that was obtained from A, and both B and A are Read/Write assignment plans,
then A should not be edited once B has been extracted.

// EXAMPLE 1: simple implementation of Calculate function

// -----------------------------------------------------HRESULT MyAFP::Calculate(
IAfpNetworkData*

netWorkData,

// provide access to network data

IInterfMatrix*

iMatrix,

// interfering probabilities

IAFPProgress*

progress,

// for cyclic reporting by Atoll

AFP_CONFIG*

config,

// from configuration

IRW_AssignmentPlan** result)

// result of assignment

{
// Some initializations

// Retrieve initial assignment Plan

// -------------------------------IAssignmentPlan* initialPlan=0;
netWorkData->GetCurrentPlan(&initialPlan);
// Initiate a current plan with the initial plan
// --------------------------------------------IRW_AssignmentPlan* current=0;
initialPlan->CreateClone(&current);
// current is created as a copy of initialPlan
// Assignment main Loop

// ASSIGNMENT:
current->SetResource(CHANNEL_TYPE,someTrg, someTrx, someChannel);

// Clean up
initialPlan->Release();

// Advice: prefer usage of smart pointers

*result = current;

// assigns current plan to the expected result

return S_OK;
}
// EXAMPLE 2: implementation of Calculate function that stores the best plan
// each time that cost is reduced of 30%
// -------------------------------------------------------------------------MyAFP::Calculate(
IAfpNetworkData*

netWorkData,

// provide access to network data

IInterfMatrix*

iMatrix,

// interfering probabilities

IAFPProgress*

progress,

// for cyclic reporting by Atoll

AFP_CONFIG*

config,

// from configuration

IRW_AssignmentPlan** result)

// result of assignment

Forsk 2007

AT260_DRG_E0

207

Developer Reference Guide

// Some initializations

// Retrieve initial assignment Plan

// -------------------------------IAssignmentPlan* initialPlan=0;

// read only

res= netWorkData->GetCurrentPlan(&initialPlan);
// Initiate a current plan with the initial plan
// --------------------------------------------float bestTotalCost= Cost(initial);
IAssignmentPlan* bestPlan= initial;
IRW_AssignmentPlan* current=0;

// read only
// read write

initialPlan->CreateClone(&current);
// current is created as a copy of initialPlan
// Assignment main Loop

// ASSIGNMENT:
current->SetResource(CHANNEL_TYPE,someTrg, someTrx, someChannel);
// EVALUATION
float newTotalCost= Cost(current);
if(newTotalCost<= 0.7* bestTotalCost) // gain over 30%
{
// store new best cost
bestTotalCost = newTotalCost;
// store new best plan
bestPlan->Release();
bestPlan = current;
// create a new clone to continue the loop based on the previous one
// in order to avoid changing the best one
bestPlan->CreateClone(&current);
}

// Clean up
initialPlan->Release();
best->CreateClone(result);

// assigns current plan to the best one

// if no 30% at least improvement has
// occurred => best==initial

current->Release();
best->Result;
return S_OK;
}

4.7.8

Reading and Writing Resources

The method GetResource/SetResource of IAssignmentPlan allows to read/write a resource number at TRX level or TRG
level in a given plan. To read or write at TRG level, you have to specify a value of 1 for the trxIndx.

// Example

208

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

// writing HSN=3 in the TRG Number 8

// --------------------------------plan->SetResource(HSN_TYPE,8,-1,3); // trx=-1 to access at TRG level
// writing CHANNEL=4 in the TRX Number 2 of TRG Number 8
// ----------------------------------------------------plan->SetResource(CHANNEL_TYPE,8,2,4);

4.7.9

TRX Manipulations
The AFP is assumed to bring a frequency plan to the state where the number of TRXs equals the number of required TRXs:

int GetDemandedNumTrx(IAfpNetworkData*

netWorkData, int trgIndex)

{
ITrg* trgp=NULL;
HRESULT ret

= netWorkData ->GetTrg(trgIndex, &trgp);

if (ret != S_OK)
return 1;
RESOURCE_TYPE type = CHANNEL_TYPE;
int dema = 0;
ret = trgp->GetDemand(type, &dema);
trgp->release();
if (ret = S_OK)
return dema;
else
return 1 ;
}
// Remark 1: If not using a smart ptr, you must not forget to release an object
//

when not using it any more.

// Remark 2: Dont forget to check the HRESULT values.

Now, assuming the AFP knows how many TRXs there should be, it may want to find out how many TRXs currently exist.
This can be done using the GetTrxCount function of an IAssignmentPlan interface. There are 3 possible cases, i.e. the
number of existing TRXs can be smaller, equal to or greater than the number of required TRXs.
Since Atoll does not approve having empty (No channel) TRXs, the AFP can change this situation only if the
ASSIGNMENT_STATE is not Frozen at TRG level:

ASSIGNMENT_STATE trg_ass_state;
thePlan->GetAssignmentState( CHANNEL_TYPE, trgIndex, -1 , &trg_ass_state);
bool is_trg_frozen = ( (trg_ass_state & FROZEN) > 0

);

Notes:

Note that the trxNumber set to 1 indicates that we are asking the TRG state. Furthermore, we will be
checking the individual TRXs to see if they were not frozen at TRX level.

Let us now assume that the AFP has found that there are already 2 existing TRXs and two more to create. It will create
the TRXs using the method AddTrxs() of the assignment plan. Then using the given number of the newly created TRXs,
it will assign their resources. If The AFP wants to examine the state of these TRXs in the future, it can check if
(trx_ass_state & CREATED) > 0. Now, for the two already existing TRXs, the AFP will try to change the resources if not
frozen:

for(short k = 0; k < num_trxs; k++)

{
int trxNumberIdentifier;
freqPlan->GetTrxNumber( trg, k, &trxNumberIdentifier);
ASSIGNMENT_STATE trx_ass_state;
thePlan->GetAssignmentState( CHANNEL_TYPE, trgIndex,
trxNumberIdentifier, &trx_ass_state);

Forsk 2007

AT260_DRG_E0

209

Developer Reference Guide

if( (trg_ass_state & FROZEN) == 0

thePlan->SetResource(CHANNEL_TYPE, trgIndex,
trxNumberIdentifier, goodFreqsArray[k])
}
If the AFP must remove any TRX, it will use the method RemoveTrx(), still considering that it should not remove Frozen
TRXs.
Notes:

4.7.10

If a TRG is Frozen at TRG level, it will definitely be Frozen at each TRX level.

In the case of resourceType = MAIO_TYPE, TRGs that are Frozen for MAIO are the ones that are out of
the focus zone / calculation zone / Transmitters folder. Otherwise, MAIO is not Frozen and should be
assigned. No special MAIO freeze flag.

The parameter AFP_BASE_CONFIG* config is the overall freezing mechanism. If, for example, ((config>allocType & MAIO_ALLOC) == 0), then no MAIOs should be allocated.

See section 4.6.1.5.1 for more details on the TO_ASSIGN and FROZEN assignment states.

Specific Case of SFH

In the specific case of SFH (Synthesized Frequency Hopping), the actual resource is a MAL (Mobile Allocation List). In
order to keep the interface homogenous with other resource types, the MAL resources passed by the methods GetResource and SetResource are assumed to be the indexes of MALs in a dedicated Read/Write grouping scheme. This dedicated grouping scheme is obtained by IAssignmentPlan.GetMAMScheme().

// -------------------------------------------------------------------------// Example: function providing the minimal channel distance between a given TRG
// and a channel value. (If this minimal channel distance is smaller than 1 then
// a Co-channel reuse exists, if it is 1 than an adj-channel reuse exists )
// -------------------------------------------------------------------------#define MAX_MAL_SIZE 1024
int GetChannelDistance(IAssignementPlan *plan,ITrg *p_trg,int channel)
{
int minDist= 1000;

// prefer MAX_INT
// retrieve some useful information
// -------------------------------

HOPPING_MODE hopMode;
p_trg->GetHoppingMode(&hopMode);
ASSIGNMENT_MODE assignMode;
p_trg->GetAssignmentMode(&assignMode) ;
int trgIndx;
p_trg->GetIndex(&trgIndx);
// find associated grouping scheme
// -------------------------------IGroupingScheme *p_gs=0;
If(hopMode!=SFH)
p_trg->GetGroupingScheme(CHANNEL_TYPE,&p_gs);
else
plan->GetFreeMALScheme(&p_gs);
// loop on TRXs
// -----------int trxCount;
plan->GetTrx(&trxCount);
int previousResource=-1;
for(int trx=0;trx<trxCount;trx++)
{

210

AT260_DRG_E0

Forsk 2007

Chapter 4: Basic AFP API

int resource;
plan->GetResource(CHANNEL_TYPE,trgIndx,trx,&resource);
if(resource==previousResource)
continue;

// case of a MAL shared by all TRXs

previousResource= resource;
if(hopMode!=SFH)// mode NONE_FH or BBH
minDist= min(minDist,ABS(channel-res)); // res is a channel value
else

// res refers to a MAL

{
// Get MAL of this trx
// ------------------int malSize=0;
p_gs->GetGroupSize(resource, &malSize);
if(malSize>MAX_MAL_SIZE)
error(Size of MAL bigger than supported by MyAFP);
int mal[MAX_MAL_SIZE];
p_gs->GetResourceNumbers(resource, malSize,mal);
// Loop on channel list of this TRX
// -------------------------------for(indxInMal =0;indxInMal <malSize; indxInMal ++)
{
minDist = min(minDist,ABS(mal[indxInMal]-channel));
}
p_gs->Release();
}
}
return minDist;
}

Forsk 2007

AT260_DRG_E0

211

Developer Reference Guide

212

AT260_DRG_E0

Forsk 2007

Chapter 5
Advanced AFP API
This chapter describes the advanced Atoll AFP API.

Developer Reference Guide

214

AT260_DRG_E0

Forsk 2007

Chapter 5: Advanced AFP API

Advanced AFP API

5.1

Multiple Interface System

In this chapter, we assume that a basic AFP has already been developped and is functioning. It implements IAfpModel::GetPlanGenerator() and IPlanGenerator::Run() while using the INetworkData, IInterfMatrix and IAfpProgress interfaces.
Now the user requires using a new feature of the AFP API. For example, the function INetwoekData2::GetNeighborImportance(), which gives the AFP access to the importance field in the Neighbours table. The INetworkData2 instance is accessible as shown below:

_COM_SMARTPTR_TYPEDEF(IAfpNetworkData2, __uuidof(IAfpNetworkData2));
IAfpNetworkData2Ptr tmp(netWorkData);
// NetworkData is an instance of IAfpNetworkData supplied by the run() function.
// It is also an instance of IAfpNetworkData2.
// The IAfpNetworkData2Ptr will create an IAfpNetworkData2 instance for you.
If (tmp == NULL)
{
// Atoll version is prior to 2.4.0, the
// IAfpNetworkData2Ptr will not be able to create an
// IAfpNetworkData2 instance for you.
// The AFP must continue without using GetNeighborImportance().
}
else
{
// tmp->GetNeighborImportance() can be called safely.
}

5.2

Read/Write Capabilities and GUI Integration

This section describes a very powerfull set of features. It is not possible to use this set of features partially, i.e. you must
implement all the methods of IAfpModel2 and IPlanGenerator2. This is because once GetPlanGenerator() returns an
object that is an IPlanGenerator2, the entire IAfpModel is assumed to be an IAfpModel2 as well.

5.2.1

New Capabilities

5.2.2

The AFP can declair its capabilities, by doing it, Atoll will propose the allocation option of these resources only.
The AFP will have a read only access to all data in the document, via the generic Api.
The AFP will have read write access to all fields of Sites, Transmitters, TRGs and TRXs tables.
The AFP could ask atoll to hide the target compution time, and or the resume button. (in the AFP output dlg)

Required Implementation
In order to have the capabilities mentioned above, the advanced AFP must implement the IAfpModel2 and
IPlanGenerator2 interfaces. This means that the AFP should implement all of the methods in IAfpModel2. The AFP should
depict its standard and costum resources when GetResourceCapabilities() is called (see example below).
Scenarios are explained in later sections. For the time-being, AFP can declare 0 senarions. All the other elements are self
explanatory.
The AFP should be ready to exploit the generic API once Atoll calls the IPlanGenerator2::OnPreload() method. It will do it
by casting the IUnknown* to an IDocument:

STDMETHODIMP CPlanGenerator::OnPreload(IUnknown* document, IResourceTypesCollection* resources)

{
IDocumentPtr doc = document;
if (doc == NULL)
return S_OK;

Forsk 2007

AT260_DRG_E0

215

Developer Reference Guide

resources->AddStandardResourceTypes(HSN_ALLOC|MAIO_ALLOC);

Notes:

5.2.3

Resources is always set to NULL (not used).

IResourceCollection, IAssignmentPlan2,
IRW_AssignmentPlan2 Interfaces
Once the AFP resource capabilities are declared, these will be proposed by Atoll to the user so that the user can select
the resources to allocate. The users selection will be communicated to the AFP via the Run() and Improve() methods. If
the AFP requires reading or writing to the standard fields (or to the AFP_RANK resource), it can do so with the
IRW_AssignmentPlan interface. If the AFP requires to use the new costum fields, it must call IResourceCollection::FindCustomResourceType() first, and use the ID thus obtained with the IRW_AssignmentPlan2 interface.
Notes:

5.3

The Get/SetCostumResource() methods use the trg and trxNumber as access keys. There may exist a
many-to-one relation when the resource level is higher than trg. For example:
Let trgs 0 to 12 belong to the same site. If a user uses SetCustomResource() for trg 1 to set a new value,
and then uses GetCustomResource() with any other trg of the site, it will return the new value that was just
set in the last step.

When declaring the AFPs resource capabilities, the corresponding buffers are created for the fields
requested by the AFP. Other fields cannot be accessed by the AFP. All AFP access requirements should
be declared in GetResourceCapabilities().

This generic mechanism eliminates the need of IAfpTransmitter (not yet implemented) or of
IRadioTransmitter2.

Scenarios Support
An AFP scenario is defined as a set of:

Name
A collection of mandatory resources
A collection of optional resources
Permission to alter existing TRXs

Forsks standard AFP does not use scenarios. Scenarios can be useful in order to reduce or limit the AFP flexibility and/
or hide some OMC parameters from the user.

5.4

New Services Provided by INetworkData2

These new services are mostly self explanatory. The principal part of these functionalities is the management of new ID
spaces: for sites, cells, TRGs and TRXTypes. These provide an alternative for the GetRelation() mechanism. In addition,
there is an access option to the separation rules (AFP launch wizard), neighbour importance, BSIC components (depending on their representation in the Atoll project), and a temporary utility for external IM use explained below.

5.4.1

Temporary Method: INetworkData2::ReadIMFile()

This function permits the AFP to supply its own IM files. The files extention and format should be compatible with one
another and supported by Atoll. A list of currently suuported formats and their explanations are available in the User
Manual. When this function is called, Atoll will read the file for the AFP and create a IInterfMatrix for it.
Caution:

5.5

This service is temporary and will not be supported for a long time. In future versions, the AFP interface will
evolve to permit multiple IM access in the AFP.

AFP API Code

import "AtollApi.idl";
// ===================================================================
// Atoll-AFP interface, V-2.

216

AT260_DRG_E0

Forsk 2007

Chapter 5: Advanced AFP API

// The first release of the Atoll-AFP interface is fully present in the

// V-2 version. Atoll will remain compatible with the older releases.
// ===================================================================

import "oaidl.idl";
import "ocidl.idl";

// {5C9CB832-A0C6-4988-995D-EBC0609209F2}
cpp_quote("EXTERN_GUID(CATID_AFP,0x5c9cb832, 0xa0c6, 0x4988, 0x99, 0x5d, 0xeb,
0xc0, 0x60, 0x92, 0x9, 0xf2);")

interface IPlanGenerator;

// generates a new assignment plan

interface IPlanGenerator2;

// generates a new assignment plan with a more

// powerful interface

interface IAfpNetworkData;

// access to network data

interface IInterfMatrix;

// access to interference matrixes

interface IAfpProgress;
AFP state

// service provided by Atoll to report cyclically

interface IAssignmentPlan;

// interface for reading assignments

interface IRW_AssignmentPlan; // interface for reading and writing assignments

//-----------------------------------------------------------------------------------typedef enum _ALLOCATION_TYPE
{
CHANNEL_ALLOC

= 0x1,

HSN_ALLOC
to expect

// Based on the allocation types exaged between

= 0x2,

// Atoll and the AFP, each will know what

MAIO_ALLOC

= 0x8,

BSIC_ALLOC

= 0x10,

// from the other

MAL_ALLOC

= 0x20,

// All the above are used.

CODE_ALLOC

= 0x40,

// Not Used

GID_ALLOC

= 0x80,

TRX_RANK

= 0x100

ALLOCATION_TYPE;

typedef enum _ALLOCATION_OPTIONS

{

QUALITY_TARGET

= 0x1,

// Not Used

COMPUTE_SEPARATION

= 0x2,

// Not Used

OPTIMIZE_INTEREFERENCE

= 0x4,

// Not Used

ADVANCED_CI_ESTIMATION

= 0x8,

ALLOCATION_OPTIONS;

typedef struct _AFP_BASE_CONFIG

{
long

duration;

int
options;
selected options )
int

Forsk 2007

allocType;

// max duration (in seconds), infinite=-1

// OR of various ALLOCATION_OPTIONS (effective
// OR of various ALLOCATION_TYPE's

AT260_DRG_E0

217

Developer Reference Guide

boolean

keepPrev;

// AFP must try to keep previous assignments

boolean

keepFrozen;

// AFP must try to keep frozen assignments

boolean
uation
int

quickEvaluation; // => user requests the simplest and quickest evalseed;

// random seed for frequency plan calculation (a -1

// value means that the AFP should generated the seed)

} AFP_BASE_CONFIG;

typedef struct _AFP_INPUT_PARAMETERS

{
long

duration;

// max duration (in seconds), infinite=-1

int
options;
selected options )

// OR of various ALLOCATION_OPTIONS (effective

boolean

keepPrev;

// AFP must try to keep previous assignments

boolean

keepFrozen;

// AFP must try to keep frozen assignments

boolean
uation
int

quickEvaluation; // => user requests the simplest and quickest evalseed;

// random seed for frequency plan calculation (a -1

// value means that the AFP should generated the seed)

} AFP_INPUT_PARAMETERS;

//-----------------------------------------------------------------------------------// Basic interfaces: IAfpModel

//-----------------------------------------------------------------------------------[
uuid(A434453A-ACC9-461E-AC70-72916425C5EF),
helpstring("IAfpModel Interface"),
pointer_default(unique)
]
interface IAfpModel: IUnknown

// MAIN interface !!

{
HRESULT GetPlanGenerator([out] IPlanGenerator** planGenerator);
}
//-----------------------------------------------------------------------------------typedef enum _ENTITY_LEVEL
{

TRX_LEVEL

=0,

TRG_LEVEL

=1,

CELL_LEVEL

=2,

SITE_LEVEL

=3

ENTITY_LEVEL;

typedef enum _FIELD_CATEGORY

{
RESOURCE_CATEGORY=0,// fields associated with this category will be
// selectable as resource to assign

218

AT260_DRG_E0

Forsk 2007

Chapter 5: Advanced AFP API

PI_CATEGORY=1,
as PIs

// fields associated with this category will be displayed

GENERIC_CATEGORY =2,// for read write access to other custom fields not displayed to the user
}

FIELD_CATEGORY;

//-----------------------------------------------------------------------------------[
uuid(898B8DF4-142C-4ac8-8F65-8E7FAAF2208A),
helpstring("ISpecifySupportedRessource Interface"),
pointer_default(unique)
]

interface IResourceTypesCollection: IUnknown

{
HRESULT AddStandardResourceTypes([in] int standardSet);
// standardSet = OR of various ALLOCATION_TYPE's
HRESULT GetStandardResourceTypes([out] int* standardSet);
// return S_OK if type is supported
HRESULT AddCustomResourceType( [in] ENTITY_LEVEL level
,[in] FIELD_CATEGORY category
,[in] BSTR fieldName
,[in] BSTR fieldTitle);
HRESULT FindCustomResourceType([in] ENTITY_LEVEL level // return S_OK if
type is supported
,[in] BSTR fieldName
,[out] int *resourceIndx);

}
//-----------------------------------------------------------------------------------// Advanced interface : IAfpModel2
//------------------------------------------------------------------------------------

//interface ISpecifyPropertyPages;
//interface IPlanEvaluator;

[
uuid(44B91C99-46EF-41be-8D94-777A0DA669F7),
helpstring("IAfpModel Interface"),
pointer_default(unique)
]

interface IAfpModel2: IAfpModel

version 2!!

// MAIN interface

// -----------------------// Resources support

Forsk 2007

AT260_DRG_E0

219

Developer Reference Guide

// -----------------------HRESULT GetResourceCapabilities([in]
edResourceTypes);

IResourceTypesCollection* support-

// -----------------------// Scenario suppport

// -----------------------HRESULT SupportsScenario([out] int *scenarioCount); // return S_OK if
support
HRESULT GetScenario([in]
,[in]

int indxScenario
IResourceTypesCollection* madandatorySelection

// to be filled
,[in]

IResourceTypesCollection* optionalSelection

// to be filled
,[out] boolean*

trxExtensionOnly

,[out] BSTR*

scenarioName);

// if optionalSelection is filled up, a page will be display to select

// optional resource type to assign

// -----------------------// Features support

// -----------------------HRESULT SupportTargetTime();

// return S_OK if target time is supported

HRESULT SupportResume();

// return S_OK if AFP can be resumed

// ---------------------------------------------------// GUI capabilities

// ---------------------------------------------------// HRESULT GetCustomWizzard(ISpecifyPropertyPages** ispp);
// return E_NOTIMPL to inherit from default AFP Atoll wizzard
}

// ---------------------------------------------------------------------------------[
uuid(49BC1603-DDF6-4E17-B5C4-511B650B834B),
helpstring("IPlanGenerator Interface"),
pointer_default(unique)
]
interface IPlanGenerator: IUnknown
{

HRESULT Run(// generate a new plan

[in] IAfpNetworkData*
[in]
[in]
[in]

netWorkData, // provide access to network data

IInterfMatrix*
IAfpProgress*

iMatrix,
progress,

AFP_BASE_CONFIG*

config,

[out] IRW_AssignmentPlan** result);

// interfering probabilities
// for cyclic reporting by Atoll
// from configuration
// result of assignment

// to generate a result plan, the plan Generator is assumed to:

// 1) retrieve the current plan using the GetCurrentPlan method of
IAfpNetworkData

220

AT260_DRG_E0

Forsk 2007

Chapter 5: Advanced AFP API

// 2) Create a new plan using the CreatePlan method of IAssignmentPlan

// 3) Modifing/Optimizing this new plan using SetResource method of
IRWAssignmentPlan
// 4) Return this optimized solution in this last parameter

HRESULT Improve(

// generates an improved plan from an existing one

[in] IAfpNetworkData*
[in]

netWorkData, // provide access to network data

IInterfMatrix*

[in]

IAfpProgress*

[in]

AFP_BASE_CONFIG*

[in] IAssignmentPlan*

iMatrix,

// interfering probabilities

progress,

// for cyclic reporting by Atoll

config,

// from configuration

previous,

// result of previous assignment

[out] IRW_AssignmentPlan** result);

// result of assignment

}
// --------------------------------------------------------------------------------[
uuid(48BC2609-ABC1-4F32-B7D1-824A742E121B),
helpstring("IPlanGenerator2 Interface"),
pointer_default(unique)
]
interface IPlanGenerator2: IPlanGenerator
{
HRESULT OnPreload([in] IUnknown* document,[in]
resources);

IResourceTypesCollection*

// access to doc, Remark: resources is NULL and not used.

HRESULT Run(// generate a new plan

[in]
network data

IAfpNetworkData*

[in] IInterfMatrix*

netWorkData, // provide access to

iMatrix,

// interfering probabilities

[in]

IAfpProgress*

progress,

// for cyclic reporting

[in]

AFP_INPUT_PARAMETERS*

parameters,

// from configuration

[in]

IResourceTypesCollection*

resources,

//

[in]

int

scenario,

// -1 => free

[in]

HWND

by Atoll

parentWnd,

[out] IRW_AssignmentPlan**

HRESULT Improve(
existing one
[in]
network data

result);

// result of assignment

// generates an improved plan from an

IAfpNetworkData*

[in] IInterfMatrix*

netWorkData, // provide access to

iMatrix,

// interfering probabilities

[in]

IAfpProgress*

progress,

// for cyclic reporting

[in]

AFP_INPUT_PARAMETERS*

options,

// from configuration

[in]

IResourceTypesCollection* resources,

by Atoll

[in]

IAssignmentPlan*

previous,

// from configuration
// result of previous

assignment
[in]

int

scenario,

[in]

HWND

parentWnd,

[out] IRW_AssignmentPlan**

Forsk 2007

AT260_DRG_E0

result);

// -1 => free

// result of assignment

221

Developer Reference Guide

HRESULT Evaluate(// evaluate a existing plan

[in]
network data

IAfpNetworkData*

netWorkData, // provide access to

[in] IInterfMatrix*

iMatrix,

// interfering probabilities

[in]

IAfpProgress*

progress,

// for cyclic reporting

[in]

AFP_INPUT_PARAMETERS*

parameters,

// from configuration

[in]

IResourceTypesCollection*

resources,

//

[in]

int

scenario,

// -1 => free

[in]

HWND

parentWnd,

//

by Atoll

[out] IRW_AssignmentPlan**

result,

[out] float* totalCost);

// result of assignment
// total cost of this plan

}
// ----------------------------------------------------------------------------------

[
uuid(A902215E-010D-4423-87C5-A8978CA1DE1D),
helpstring("IAfpConfigure Interface"),
pointer_default(unique)
]
interface IAfpConfigure : IUnknown
requires
{

// to be implemented by AFP if it
// a specific configuration. Atoll will

// query for this interface and if it exists,

// atoll will use it. if not, Atoll will
// provide its standard default configuration
// dialog

HRESULT Configure([in] HWND );

// open a dialog for configuration

// parent window from which AFP is called

//
=============================================================================
======
// Interfaces of services provided by the Atoll
//
=============================================================================
=========

//----------------------------------------------------------------------------------// Default Progress : implemented by Atoll, used by AFP to display current cost
// dedicated to "cyclic progress report" of AFP process
//----------------------------------------------------------------------------------[
uuid(B87BC22F-DA8B-44B2-A9B2-F747E0C651F4),
helpstring("IAfpProgress Interface"),

222

AT260_DRG_E0

Forsk 2007

Chapter 5: Advanced AFP API

pointer_default(unique)
]
interface IAfpProgress: IUnknown
{
HRESULT StartProgressReport();// Atoll will open its default progress
// report dialog. If the AFP wants to have its
// own progress dialogue suit. It should not call
// this method.
HRESULT OnProgress([in] float softCost, [in] int sepBreak);
// to be call cyclically, softCost reports the
// state of soft constraints optimization while sepBreak
// is the number of hard separation breaking.
// return S_FALSE => stop requested by user
HRESULT Display([in] LPCWSTR

status);

// display message on the progress dialog

HRESULT DisplayLogInfo([in] LPCWSTR

infoMsg);

// display the information message and add it to the log.

HRESULT DisplayLogWarning([in] LPCWSTR

warnMsg);

// display the warning message and add it to the log.

HRESULT DisplayLogError([in] LPCWSTR

errMsg);

// display the error message and add it to the log.

}

//-----------------------------------------------------------------------------------//

Network Data for AFP purposes

//-----------------------------------------------------------------------------------// forward declarations :

interface ITrg;
of TRXs)

// access to properties of one BTS Trx group (pool

interface ITrgSeparations;
between TRX groups

// access to predefined separation requirements

//-----------------------------------------------------------------------------------typedef enum _RESOURCE_TYPE

{

CHANNEL_TYPE

= 0,

HSN_TYPE

= 1,

MAIO_TYPE

= 2,

BSIC_TYPE

= 3,

CODE_TYPE

= 4,

GID_TYPE

= 5,

TRX_RANK_TYPE

= 6

RESOURCE_TYPE;

//-----------------------------------------------------------------------------------[
uuid(8FDEF953-92A6-45D9-AF55-8C7D99AE9476),
helpstring("IAfpNetworkData Interface"),
pointer_default(unique)

Forsk 2007

AT260_DRG_E0

223

Developer Reference Guide

]
interface IAfpNetworkData: IUnknown
{

// Access to individual Trx Groups (TRGs)

// ================================
HRESULT GetTrgCount([out] int *count);

// number of TRX groups

HRESULT GetFirstTrg(
transmitter

// First TRX-group of the

[in] IRadioTransmitter2*

t,

// interface ITransmitter2

already
[out] int* firstTrgIndex);

// included in Propagation API

HRESULT GetTrg([in] int indx, [out] ITrg**);

// access to ITrg interface
of a TRX group.
// TRX groups (TRGs) are sorted by
// sites and by sectors.
HRESULT GetSeparations(
[in] RESOURCE_TYPE,
[out] ITrgSeparations** sep);
HRESULT GetCurrentPlan([out] IAssignmentPlan** plan); // provides the
current plan
}

//-----------------------------------------------------------------------------------interface IAfpTransmitter; // Fast access to the most important

// properties of a transmitter (Tx).
[
uuid(2AB1F953-A2A6-AB39-11FF-2C2DAB679231),
helpstring("IAfpNetworkData2 Interface"),
pointer_default(unique)
]
interface IAfpNetworkData2: IAfpNetworkData
{

// Cell level access

HRESULT GetTxCount([out] int *count); // Number of transmitters: "Atoll
transmitter" <=> cell <=> sector
HRESULT GetTx([in] int txIndx, [out] IAfpTransmitter**);
HRESULT GetTxId([in] int trg, [out] int* txId);
one-to-many correspondence

// The

HRESULT GetTrgCountOfTx([in] int txId, [out] int* count);

HRESULT GetTrgIds([in] int txId, [in] int count,[out, size_is(count)] int*
trgIds);

// Site level access

HRESULT GetSiteCount([out] int *count);
// Number of transmitters: "Atoll transmitter" <=>
cell <=> sector

224

AT260_DRG_E0

Forsk 2007

Chapter 5: Advanced AFP API

HRESULT GetSiteId([in] int txId, [out] int* siteId);

many correspondence

// The one-to-

HRESULT GetTxCountOfSite([in] int siteId, [out] int* count);

HRESULT GetTxIds([in] int siteId, [in] int count,[out, size_is(count)]
int* txIds);

// Access to TrxTypes
HRESULT GetTrxTypesCount([out] int *count);
HRESULT GetTrxType([in] int indx,[out] BSTR* trxTypeName);
HRESULT GetSeparationRule([in] BSTR trxType1, [in] BSTR trxType2,
[in]

int relationType,

[out] int* sep);

// Neighbour importance
HRESULT GetNeighborImportance([in] int serverTrg,

[in] int neighborTrg,

[out] float* importance);

// BSIC decoding
HRESULT SplitBsic([in] int bsic, [out] int* ncc, [out] int* bcc);
// If the BSIC is not legal, this function will return E_FAIL.
HRESULT ReadIMFile([in] BSTR filePath, IInterfMatrix** im);
}

//-----------------------------------------------------------------------------------//
//
//
//
//
//

Trx groups: group of TRXs that belong to the same cell

and have a specific usage
Example of trx groups:
- BCCH group of BTS1 ( group containing only 1 TRX)
- TCH group of BTS1 ( define also the TCH_outer in concentric cells)
- TCH_inner of BTS1 ( list of TRX dedicated to overlay cell)

//-----------------------------------------------------------------------------------interface IGroupingScheme;
resource groups)

// read access to grouping scheme (list of

interface IDynamicGroupingScheme;

// read-write access to grouping scheme

interface IFrequencyBand;

// access to frequency band

//-----------------------------------------------------------------------------------typedef enum _ASSIGNMENT_MODE

{

FREE_ASSIGNENT

= 0,

GROUP_ASSIGNENT

= 1,

ASSIGNMENT_MODE;

//-----------------------------------------------------------------------------------typedef enum _ASSIGNMENT_STATE

{

Forsk 2007

// Means :

TO_ASSIGN = 0x1,
resource type)

// TRXs or TRGs selected for assignment (for a certain

FROZEN
= 0x2,
resource type)

// TRXs or TRGs forbidden for assignment (for a certain

AT260_DRG_E0

225

Developer Reference Guide

MODIFIED
assigned.

= 0x4,

// TRXs or TRGs for which a certain resource type was

CREATED
= 0x8
be created!!)
}

// this TRX was created by the AFP (remark: TRGs can not

ASSIGNMENT_STATE;

//-----------------------------------------------------------------------------------typedef enum _HOPPING_MODE

{

NONE_FH

= 0,

BFH

= 1,

SFH

= 2

HOPPING_MODE;

//-----------------------------------------------------------------------------------typedef enum _AFP_RELATION_TYPE

{
COSITE

= 0x1,

COCELL

= 0x2,

NEIGHBOUR

= 0x4,

SYNCHRO
agement
SPECIAL
COTRG
then others)
}

= 0x8,

// relation specify synchronized TRXs for MAIO man-

= 0x10, // for exceptional relations (eg: separation exception)

= 0x20

// (in some cases inter-trg separations can be higher

AFP_RELATION_TYPE;

//-----------------------------------------------------------------------------------// Quality metric allow user to express quality thresholds

// in various metric (C/I, BER, ...)
// currently: only CI is supported
//-----------------------------------------------------------------------------------typedef enum _QUALITY_METRIC
{
CI

= 0,

// default

RBER

= 1,

// bit error rate

FER

= 2,

// frame erasure rate (for control Channel)

BLER

= 3,

// block error rate ( for packet services)

MOS

= 4, // mean option score (value 5. =EXCELLENT, value 0.= BAD)

USER_DEFINED
}

= 5

// see IQualityModel interface

QUALITY_METRIC;

//------------------------------------------------------------------------------------

[
uuid(2707F4C7-9F43-4F5F-8934-24BB51A11AC2),
helpstring("ITrg Interface"),
pointer_default(unique)
]
//---------------------------------------------------------interface ITrg: IUnknown

226

AT260_DRG_E0

// Access to a trx group

Forsk 2007

Chapter 5: Advanced AFP API

//---------------------------------------------------------{
HRESULT GetIndx([out] int *indx);

// indx of the TRX-group

// in the AfPNetworkData

HRESULT GetTrxType([out]
"BCCH","TCH","TCH_Inner".

BSTR*

HRESULT ContainsBroadcastChannel();

//

examples:

// S_OK => true, S_FALSE => false

HRESULT GetGroupingScheme(
[in]

trgType);

// allowed GS for allocation

RESOURCE_TYPE type,

[out] IGroupingScheme** gs);

HRESULT GetFrequencyBand(
[out] IFrequencyBand** gs);
HRESULT GetDemand(
[in]

RESOURCE_TYPE type,

[out] int* demand);

// required trx' number

HRESULT GetTrafficLoad([out] float* traffic);

HRESULT GetDLTimeSlotUseRatio([out] float* tsExp);
// Average Time slot exploitation ratio at down-link
HRESULT GetCostWeightingFactor([out] float* factor);
// weighting of this trx Group (default=1.)
HRESULT GetHoppingMode([out] HOPPING_MODE* mode);
HRESULT GetAssignmentMode([out] ASSIGNMENT_MODE* mode);
HRESULT GetMALSize([out] int* sz);

// for SFH only

// Relations cosite, cocell & neighbourhood

// (Does not include the special separation relation!!)
// ---------------------------------------HRESULT IsInRelation(
[in] AFP_RELATION_TYPE type,
[in] int trgIndx);

// return S_OK or S_FALSE

HRESULT GetTrgRelationCount(
[in] AFP_RELATION_TYPE type, // Type is strictly a single relation
type
[out] int* count);

// number of relations

HRESULT GetTrgRelation(
[in] AFP_RELATION_TYPE type,
[in] int count,

// read size

[out, size_is(count)] int* TrgIndexes);

// number of relations

HRESULT GetTransmitter(
[out] IRadioTransmitter2** tr);

// Quality Target:
// ==============
// HRESULT GetQualityModel([out] IQualityModel** qm); => Future use
HRESULT GetQualityThreshold(
unsupported

// return E_NOTIMPL =>metric

[out] QUALITY_METRIC *metric, // unit of qmin (default= CI)

[out] float* qmin);

// min value of quality required

HRESULT GetProbabilityThreshold(
[out] float* minProba);

Forsk 2007

AT260_DRG_E0

227

Developer Reference Guide

}
//-------------------------------------------------------------------------------------------

[
uuid(9CC02198-13D6-4C18-961F-0160EE828C61),
helpstring("ITrg2 Interface"),
pointer_default(unique)
]
interface ITrg2: ITrg

// Access to a trx group

//---------------------------------------------------------{
HRESULT GetSucellTrafic([out] float* voiceTrafic,
// average number of timeslot serving voice
[out] float* paquetTrafic,
// average number of timeslot serving
paquet services
[out] float* signallingTafic);
// average number of timeslot serving
isgnalisation

HRESULT GetRequiredTS(

[out] int* csOnlyTS,

[out] int* sharedTS,
[out] int* psOnlyTS,
[out] int* signallingTs);

HRESULT GetTimeSlotAverageVoiceCapacity([out] float* erlangPerTs);

HRESULT GetTimeSlotAveragePaquetCapacity([out] float* throughputPerTs);
HRESULT GetRrmUnit([out] int*rrmUnit);
HRESULT GetBaseBandUnit([out] int*bbhUnit);
HRESULT GetAveragePowerControl([out] float* averagePowerControl);
}

//------------------------------------------------------------------------------------------[
uuid(24A57CA7-4F33-ED32-8934-2434A3B71AC2),
helpstring("IAfpTransmitter Interface"),
pointer_default(unique)
]
//---------------------------------------------------------interface IAfpTransmitter: IRadioTransmitter2 // Access to a the basic transmitter properties
//---------------------------------------------------------{
HRESULT GetName([out] BSTR* name);
HRESULT GetLocation([out] float* x, [out] float* y, [out] float* mntHigth);
// Two transmitters have the same site if and only if their (x,y,z) are
the same.
HRESULT GetHcsLayerPriority( [out] int* priority);
}

228

AT260_DRG_E0

Forsk 2007

Chapter 5: Advanced AFP API

//-------------------------------------------------------------------------------------------

//-----------------------------------------------------------------------------------// Read Only Assignment Plan

// ------------------------// (correspondance between trx and resource Numbers (Channel, HSN, MAIO,...) )
// Exclusive Usage: read of current assignments
//-----------------------------------------------------------------------------------// forward declaration:
interface IRW_AssignmentPlan;

[
uuid(39451C22-FB24-42C1-A14C-AA65083A8321),
helpstring("IAssignmentPlan Interface"),
pointer_default(unique)
]
interface IAssignmentPlan: IUnknown
{
HRESULT CreateClone([out] IRW_AssignmentPlan** clone);
// creates a read/write clone based on the current one

// Trx count & numbering

//--------------------------------------------------------HRESULT GetTrxCount([in] int trgIndx,[out] short* trxCount);
HRESULT GetTrxNumber([in] int trgIndx,[in] short trxIndx,[out] int* trxNumber);
// trxIndex is the ID space
[0, GetTrxCount()-1]
HRESULT GetTrxIndex([in]
trxIndx);

int trgIndx,[in] int trxNumber,[out] short*

// Warning: When trxs are

added or remove
// indexs may go out of scope or point to
// variating trxs.
HRESULT GetTrxNumbers([in] int trgIndx,
[in] short count,
[out,size_is(count)] int* trxNumbers);
// Gets all numbers at once.

// partial allocation

& Freezing

//--------------------------------------------------------HRESULT GetAssignmentState(
& trx groups

Forsk 2007

[in]

RESOURCE_TYPE type,

[in]

int

trgIndx,

AT260_DRG_E0

// assignment state of trx

// trgIndx

229

Developer Reference Guide

[in]

int

trxNumber,

// if trxNumber == -1

=>

trg state
[out] ASSIGNMENT_STATE* state);

// is assumed to be demanded

// ----------------------------------------------------// read of resource number at Trx & TrxGroup level

// ----------------------------------------------------// if the Hopping mode of the trx group is "SFH" and resource type is
CHANNEL_TYPE
//
method)

res refers to the group number of the MAL scheme (see following

//
// In all other cases res is the resource number (ARFCN, HSN, MAIO, BSIC,
...)
//---------------------------------------------------------------------------------HRESULT GetResource(
[in] RESOURCE_TYPE type,
[in] int
[in] int

trgIndx,

// indx of the trx group

trxNumber,

// N of trx in the transmitter

// (use -1 for Trg level access)

[out] int *res);

// res=-1 means unassigned

// --------------------------------------------------------------------------// Dynamic MAL management.(group scheme used for temporary storage of free
MAL)
// --------------------------------------------------------------------------HRESULT GetMALScheme([out] IDynamicGroupingScheme** scheme); // static or
dynamic
}
//------------------------------------------------------------------------------------------[
uuid(2900AAC7-4F03-ED32-8004-243010BED10A),
helpstring("IAssignmentPlan2 Interface"),
pointer_default(unique)
]
interface IAssignmentPlan2: IUnknown

// Get this from a IAssignmentPlan

{
HRESULT GetCustomResource(
[in] int
lection::GetCustomResource
[in] int
level. according to

resourceIndx,// obtained from IResourceTypesColtrgIndx,

// each resourceIndx has its associated

// this level, the trgIndex will be used.

If the level is
// TRG or TRX levels, the trg is simply
a trg. If it is
// CELL or SITE levels, the trgIndx is one
of the trg's in
// the CELL or SITE.
[in] int

230

trxNumber,
AT260_DRG_E0

Forsk 2007

Chapter 5: Advanced AFP API

// N of trx in the transmitter (use -1 for

Trg level access)
[out] VARIANT*

res);

}
//-----------------------------------------------------------------------------------// interface IRW_AssignmentPlan : Read Write Assignment Plan
// (correspondance between trx and resource Numbers (Channel, HSN, MAIO,...) )
// Usage: read of current assignments and write of new ones
//-----------------------------------------------------------------------------------[
uuid(6A9C1110-2D99-4D13-B6F8-AAA01D8734FE),
helpstring("IRW_AssignmentPlan Interface"),
pointer_default(unique)
]
interface IRW_AssignmentPlan: IAssignmentPlan // Assignment plan with read/
write access
{

// Trx edition
//--------------------------------------------------------HRESULT AddTrxs([in] int trgIndx,
[in] short newTrxCount,
[out, size_is(newTrxCount)] int* newTrxNumbers);
// trxCount: number of added trxs
// All new trxnumbers
will be put in a
//

pre-dimentioned ar-

ray: newTrxNumbers[]
HRESULT RemoveTrx([in] int trgIndx,[in] int trxNumber);
// trxNumber: indx
in the transmitter

// Write of resource number at Trx & TrxGroup level

// ----------------------------------------------------// ( see definition of res in the IAssignmentPlan interface)
//---------------------------------------------------------------------------------HRESULT SetResource(
[in] RESOURCE_TYPE type,
[in] int

trgIndx,

// obtained from

ISelectedResource
[in] int

trxNumber,

// N of trx in the trx group

// (use -1 for Trx

groups level access)

[in] int res);

// res=-1 means unassigned

//-------------------------------------------------------------------------------------------

Forsk 2007

AT260_DRG_E0

231

Developer Reference Guide

[
uuid(2A98605E-F255-48a3-9ABD-7BFD4B4C80AF),
helpstring("IRW_AssignmentPlan2 Interface"),
pointer_default(unique)
]
interface IRW_AssignmentPlan2: IUnknown
{
HRESULT SetCustomResource(
[in] int
[in] int

resourceId,

//Can be a custom resource

trgIndx, // each resourceIndx has its associated level.

according to
// this level, the trgIndex will be used. If
the level is
// TRG or TRX levels, the trg is simply a trg.
If it is CELL or
//

SITE levels, the trgIndx is one of the trg's

in the CELL or SITE.

[in] int
Trg level access)

trxNumber, //N of trx in the transmitter (use -1 for

[in] VARIANT value);

}
//-----------------------------------------------------------------------------------// Separation Constraints
//-----------------------------------------------------------------------------------[
uuid(70158FF2-224E-4AE1-9E2C-2442A2A82900),
helpstring("ITrgSeparations Interface"),
pointer_default(unique)
]
interface ITrgSeparations: IUnknown
{
// "Matrix like" access

(the simplest)

// -----------------------------------HRESULT GetSeparation(
[in] int type,

// combination different AFP_RELATION_TYPE

[in] int trg1,

// index of trx group 1

[in] int trg2,

// index of trx group 2

[out] int* sep); // separation required by the highest

priority AFP_RELATION_TYPE
// (For example, if trg1 and trg2 are cosite and neighbours,
//

the highest prriority relation type

will be co-site)

//###################################################################
// No Longer supported. For getting the defult separation, use

// the GetSeparationRule function in thr IAfpNetworkData2 interface #

HRESULT GetDefaultSeparation(

232

AT260_DRG_E0

//

Forsk 2007

Chapter 5: Advanced AFP API

[in]

int type,

//

[in]

int trg,

//

//

[out] int* sep);

//###################################################################

// If trg-b is a neighbour of trg-a in AFP_RELATION_TYPE x, and if the

optimized access
// below does not return (trg-a, trg-b) as a separation
pair, then we assume the
// separation to be O. And not the default value of relation x. !!!

HRESULT GetRelationsCount(
[in] int type,

// combination of

AFP_RELATION_TYPE
[in] int trg1,

// group indx

[out] int* count);

// number of grp relationships

HRESULT GetRelation(
[in] int type,

// combination of

AFP_RELATION_TYPE
[in] int trg1,

// group indx

[in] int indx,

// index of relation

(0 to count-1)
[out] int* trg2,

// The trg

[out] int* separation);

// It's separation

//-----------------------------------------------------------------------------------// Separation Constraints improved Interface

//-----------------------------------------------------------------------------------[
uuid(70158FF2-224E-4BF1-9A2D-9342A6A83421),
helpstring("ITrgSeparations2 Interface"),
pointer_default(unique)
]
interface ITrgSeparations2: ITrgSeparations
{

HRESULT GetPriorityOfSeparationType( [in] int type,

AFP_RELATION_TYPE

// a single

[out] int* priority );

// If type A (for example COSITE) has an higher priority than type B
// (For example NEIGHBOUR) than the separation requirments between a
// pair of trgs that are both A and B, will be the separation requirment
// demanded by A (in this case, COSITE).

HRESULT GetFullSeparationInfo(
[in] int type,

Forsk 2007

AT260_DRG_E0

// combination different AFP_RELATION_TYPE

233

Developer Reference Guide

[in] int trg1,

// index of trx group 1

[in] int trg2,

// index of trx group 2

[out] int* sep,

priority AFP_RELATION_TYPE

// separation required by the highest

[out] int* dominantType); // the highest priority

AFP_RELATION_TYPE

//-----------------------------------------------------------------------------------// Access to Calculation results

//-----------------------------------------------------------------------------------[
uuid(F391F635-BDE1-41E9-88BD-737045AC8E77),
helpstring("IInterfMatrix Interface"),
pointer_default(unique)
]
interface IInterfMatrix: IUnknown // include Power Offset ( du to power Control)
{
//
HRESULT GetHistogramSize(
[in] int trgv,

// trg indx of victim

[out] int* nThresh);

// "Matrix like" access

// in order to dimension histograms

(the simplest)

// -----------------------------------HRESULT GetInterferingHistogram(
[in] int trgv,

// trg indx of victim

[in] int trgi,

// trg indx of interferer

[in] int maxCount,

// The size

to which the arrays are dimensioned.

[out] int*
histogram (at least 2)

count,

// number of thresholds of

[out, size_is(maxCount)] float* threholds, // C/I thresholds

int db
[out, size_is(maxCount)] float* probas);
for C/I to be under thresholds

HRESULT GetInterferingProbability(
threshold

// probabilities

// simplified access for one

[in] int trgv,

// trg number of victim

[in] int trgi,

// trg indx of interferer

[in] float CI_threshold,

// C/I threshold

[out] float* proba);

// probabilities for C/I to

be under threshold
// (maybe interpolated)

// optimized access (avoid scan of all possible pairs of TRGs)

234

AT260_DRG_E0

Forsk 2007

Chapter 5: Advanced AFP API

// once we get the interferers, we can access the interference histogram with
// the simple access above.
// -----------------------------------------------------------------HRESULT GetInterfererCount(
[in] int trgv,

// trg index of victim

[out] int* count);

// number of interferers of trgv

HRESULT GetInterferers(
[in] int trgv,

// trg index of victim

[in] int count,

// memory bound on the number

of interferers
[out,size_is(count)] int* trgi);

// trgIn-

dexes of interferers

// optimized access in the Interfrere to victims direction

// once we get the victims, we can access the interference histogram with
// the simple access above.
// -----------------------------------------------------------------HRESULT GetVictimCount(
[in] int trgi,

// trg index of interferer

[out] int* count);

// number of victimss of trgi

HRESULT GetVictims(
[in] int trgi,

// trg index of interferer

[in] int count,

// memory bound on the number

of victims
[out,size_is(count)] int* trgv);

// trg in-

dexes of victims.

// Special optimized access. Faster then the combination of GetInterferers() and then
// GetInterferingHistogram()
HRESULT GetInterfererHistogram(
[in] int trgv,
[in] int indx,
[out] int* trgi,

// trg index of victim

// relation indx (0 to count-1)
// trg index of interferer

[in] int maxCount,

histogram (by which arrays were dimensioned)

// number of thresholds of
// It is used

since only a global histogram size is available.

[out] int* count,

// number of thresholds returned

[out, size_is(maxCount)] float* threholds,

// C/I thresholds
[out, size_is(maxCount)] float* probas);
// probabilities for
C/I to be under thresholds
}
//-----------------------------------------------------------------------------------// Access to Grouping schemes (list of groups of resource numbers)
// resource numbers can be ARFCN (channel numbers, HSN, MAIO, ...)
//------------------------------------------------------------------------------------

Forsk 2007

AT260_DRG_E0

235

Developer Reference Guide

[
uuid(10C64AA3-9B6C-4A8C-BA5A-D907F668BD84),
helpstring("IGroupingScheme Interface"),
pointer_default(unique)
]

interface IGroupingScheme: IUnknown //domain or list of groups of resource

numbers
{
HRESULT GetGroupingSchemeID([out] VARIANT *id);

// A Unique identifier of
// the

grouping scheme.

HRESULT GetGroupCount([out] int *count);

// number of groups
// included in scheme

HRESULT GetGroupSize (
[in]

int grpIndx,

// indx of group

[out] int *size);

// size groups included

HRESULT GetResourceNumbers(
[in]

int grpIndx,

// indx of group

[in]

int count,

// read size

[out,size_is(count)] int *numbers);

// resource num (ARFCN,

HSN,MAIO...)

HRESULT Contains(
grpIndx contains r
[in]
[in]

// return S_OK if group

int grpIndx,

int r);

// indx of group
// resource number searched

}
//-----------------------------------------------------------------------------------// Dynamic group allow storage by AFP of Hopping groups (MAL)
//-----------------------------------------------------------------------------------[
uuid(7005576C-3614-4FF5-A16B-AD59C96A7578),
helpstring("IDynamicGroupingScheme Interface"),
pointer_default(unique)
]

interface IDynamicGroupingScheme: IGroupingScheme //Write access Group

scheme
{
HRESULT AddGrp([in] int grpSz,[out] int* grpIndx);
HRESULT DeleteGrp([in] int grpIndx);
HRESULT SetGrp([in] int grpIndx,[in] int grpSz,[in, size_is(grpSz)] int
*numbers);
}
//-----------------------------------------------------------------------------------/*

===================================================
Interface of Quality model: TO BE defined (Future)

236

AT260_DRG_E0

Forsk 2007

Chapter 5: Advanced AFP API

==================================================
interface IQualityModel: IUnknown
{
}
*/
//-----------------------------------------------------------------------------------// Frequency band
//-----------------------------------------------------------------------------------[
uuid(4225B739-9052-4642-BA25-37FBD228CCFF),
helpstring("IFrequencyBand Interface"),
pointer_default(unique)
]
interface IFrequencyBand: IUnknown
{
HRESULT GetMultiPlexingFactor([out] int* factor);
HRESULT GetCoherenceBandWidth([out] int* widthInChannels);
HRESULT GetAdjascentSuppression([in] int n, [out]float *asupp);
// returns the n'th adjascent suppression
in DBs
}

Forsk 2007

AT260_DRG_E0

237

Developer Reference Guide

238

AT260_DRG_E0

Forsk 2007

Developer Reference Guide

Forsk 2007

AT260_DRG_E0

239

Developer Reference Guide

Release 2.6.0
7 rue des briquetiers 31700 Blagnac France
Tel: +33 (0)5 62 74 72 10 Fax: +33 (0)5 62 74 72 11
http://www.forsk.com

AT260_DRG_E0
February 2007