DeveloperReference

Guide2.6.0

AT260_DRG_E0

Developer Reference GuideContact Information

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/copiedunder the terms and conditions of the license agreement. No part of this document may be copied, reproduced or distrib-uted 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 reg-istering parties.

About Developer Reference GuideThis document contains information on the Atoll Development Kit and APIs. The Developer Reference Guide is aimed atreaders concerned with programming using the Atoll API. This guide describes how to use the Atoll Development Kit andhow to develop interfaces using the APIs. It also provides examples and references for better understanding and in orderto 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 DevelopmentKit. The next three chapters respectively contain details of three different APIs available, the Propagation API, the GeneralAPI, and the AFP API.

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

L

{

www.forsk.comforsk@forsk.comsales@forsk.comsupport@forsk.com+33 (0) 562 74 72 10+33 (0) 562 74 72 25+33 (0) 562 74 72 11

WebGeneral informationSales and pricing informationTechnical supportGeneralTechnical supportFax

Forsk (USA Office) 200 South Wacker Drive Suite 3100 Chicago, IL 60606 USA

L{

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

Sales and pricing informationTechnical supportGeneralTechnical supportFax

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.cnenquiries@forsk.com.cn+86 20 8553 8938+86 20 8553 8285+86 10 6513 4559

WebInformation and enquiriesTelephoneFax (Guangzhou)Fax (Beijing) Forsk 2007 AT260_DRG_E0 iii

Developer Reference Guideiv AT260_DRG_E0 Forsk 2007

Table of ContentsTable of Contents

1 Introduction ..................................................................................... 191.1 Getting Started ....................................................................................................................................... 191.2 Prerequisites .......................................................................................................................................... 191.3 Supported Extensions ............................................................................................................................ 19

1.3.1 Propagation Models ......................................................................................................................... 191.3.2 Add-ins ............................................................................................................................................. 191.3.3 Macros.............................................................................................................................................. 201.3.4 Scripts .............................................................................................................................................. 201.3.5 Automatic Frequency Planning Models ............................................................................................ 201.3.6 Mixing Extensions ............................................................................................................................ 20

2 Propagation API.............................................................................. 232.1 Propagation Models in Atoll ................................................................................................................... 232.2 Propagation Model Tutorial .................................................................................................................... 23

2.2.1 Step 1: Creating The Propagation Model Project ............................................................................. 232.2.2 Step 2: Adding The Propagation Model ........................................................................................... 242.2.3 Step 3: Returning Meaningful Errors ................................................................................................ 252.2.4 Step 4: Adding Properties ................................................................................................................ 252.2.5 Step 5: Adding a Property Page ....................................................................................................... 272.2.6 Step 6: Adding Persistence .............................................................................................................. 302.2.7 Step 7: Adding Notifications ............................................................................................................. 31

2.3 Reference Guide .................................................................................................................................... 312.3.1 Structures ......................................................................................................................................... 32

2.3.1.1 Polarization ................................................................................................................................. 322.3.1.2 Pixel_Type .................................................................................................................................. 322.3.1.3 Extraction_Mode......................................................................................................................... 322.3.1.4 Geopoint and Georect Structures ............................................................................................... 32

2.3.2 Model Interfaces ............................................................................................................................... 322.3.2.1 Used COM Interfaces ................................................................................................................. 332.3.2.2 IPropagationModel Interface....................................................................................................... 33

2.3.2.2.1 IPropagationModel::CalculateGrid Method ........................................................................... 332.3.2.2.2 IPropagationModel::CalculatePoints Method ........................................................................ 34

2.3.2.3 IMultiResPropagationModel Interface......................................................................................... 352.3.2.3.1 IMultiResPropagationModel::CalculateGrids Method ........................................................... 352.3.2.3.2 CalculateGrids Implementation Example .............................................................................. 35

2.3.2.4 IOnProfilePropagationModel and IOnProfilePropagationModel2 Interfaces............................... 382.3.2.4.1 IOnProfilePropagationModel::CalculateProfile Method......................................................... 382.3.2.4.2 IOnProfilePropagationModel2::ShowDetails Method ............................................................ 39

2.3.2.5 ITransmitterAntennaLossesNotIncluded Interface...................................................................... 392.3.3 Atoll Interfaces.................................................................................................................................. 40

2.3.3.1 IRasterGeoData Interface........................................................................................................... 402.3.3.1.1 IRasterGeoData::GetBoundingBox Method .......................................................................... 402.3.3.1.2 IRasterGeoData::GetGridResolution Method........................................................................ 412.3.3.1.3 IRasterGeoData::ExtractProfile Method................................................................................ 412.3.3.1.4 IRasterGeoData::GetValue Method ...................................................................................... 412.3.3.1.5 IRasterGeoData::PrepareFastAccessData Method .............................................................. 42

2.3.3.2 IMultiGridData Interface.............................................................................................................. 422.3.3.2.1 IMultiGridData::EnumDataSet Method.................................................................................. 42

2.3.3.3 IClutterInfo Interface ................................................................................................................... 432.3.3.3.1 IClutterInfo::GetCount Method .............................................................................................. 432.3.3.3.2 IClutterInfo::GetItemProperties Method ................................................................................ 43

2.3.3.4 IEnumGridData Interface ............................................................................................................ 432.3.3.4.1 IEnumGridData::Next Method ............................................................................................... 442.3.3.4.2 IEnumGridData::Skip Method ............................................................................................... 442.3.3.4.3 IEnumGridData::Reset Method ............................................................................................. 442.3.3.4.4 IEnumGridData::Clone Method ............................................................................................. 44

2.3.3.5 IGridData Interface ..................................................................................................................... 452.3.3.5.1 IGridData::GetDimension Method ......................................................................................... 452.3.3.5.2 IGridData::GetPixelType Method .......................................................................................... 45 Forsk 2007 AT260_DRG_E0 v

Developer Reference Guide2.3.3.5.3 IGridData::ExtractSubGrid Method ........................................................................................462.3.3.6 IRadioTransmitter, IRadioTransmitter2 and IRadioTransmitter3 Interfaces ................................46

2.3.3.6.1 IRadioTransmitter::GetHeight Method ...................................................................................472.3.3.6.2 IRadioTransmitter::GetAltitude Method .................................................................................472.3.3.6.3 IRadioTransmitter::GetAzimut Method ..................................................................................472.3.3.6.4 IRadioTransmitter::GetTilt Method.........................................................................................472.3.3.6.5 IRadioTransmitter::GetFrequency Method ............................................................................472.3.3.6.6 IRadioTransmitter::GetLocation Method ................................................................................482.3.3.6.7 IRadioTransmitter::GetPolarization Method...........................................................................482.3.3.6.8 IRadioTransmitter::GetAntennaLoss Method ........................................................................482.3.3.6.9 IRadioTransmitter::GetCalculationZone Method ...................................................................482.3.3.6.10 IRadioTransmitter2::GetTransmitterId Method ......................................................................492.3.3.6.11 IRadioTransmitter2::GetEirp Method .....................................................................................492.3.3.6.12 IRadioTransmitter2::GetFieldValue Method ..........................................................................492.3.3.6.13 IRadioTransmitter3::EnumAntennas Method.........................................................................50

2.3.3.7 IRadioReceiver Interface .............................................................................................................502.3.3.7.1 IRadioReceiver::GetHeight Method .......................................................................................50

2.3.3.8 IProgressCallback, IProgressCallback2 and IProgressCallback3 Interfaces ..............................512.3.3.8.1 IProgressCallback::OnProgress Method ...............................................................................512.3.3.8.2 IProgressCallback2::SetStatusText Method ..........................................................................512.3.3.8.3 IProgressCallback3::LogEvent Method .................................................................................51

2.3.3.9 IMultiResolution Interface ............................................................................................................522.3.3.9.1 IMultiResolution::GetCount Method.......................................................................................522.3.3.9.2 IMultiResolution::GetResolution Method ...............................................................................52

2.3.3.10 IMeasurements Method...............................................................................................................522.3.3.10.1 IMeasurements::GetName Method........................................................................................532.3.3.10.2 IMeasurements::GetTransmitter Method ...............................................................................532.3.3.10.3 IMeasurements::GetReceptionHeight Method.......................................................................532.3.3.10.4 IMeasurements::GetCount Method........................................................................................532.3.3.10.5 IMeasurements::GetLocations Method..................................................................................532.3.3.10.6 IMeasurements::GetMeasurements Method .........................................................................54

2.3.3.11 IEnumMeasurements Interface ...................................................................................................542.3.3.11.1 IEnumMeasurements::Next Method ......................................................................................542.3.3.11.2 IEnumMeasurements::Skip Method.......................................................................................552.3.3.11.3 IEnumMeasurements::Reset Method ....................................................................................552.3.3.11.4 IEnumMeasurements::Clone Method ....................................................................................55

2.3.3.12 IMeasurementsCatalog Interface ................................................................................................552.3.3.12.1 IMeasurementsCatalog::EnumMeasurements Method .........................................................552.3.3.12.2 IEnumGridData::Skip Method ................................................................................................562.3.3.12.3 IEnumGridData::Reset Method..............................................................................................562.3.3.12.4 IEnumGridData::Clone Method..............................................................................................56

2.3.3.13 IAntenna Interface .......................................................................................................................562.3.3.13.1 IAntenna::GetFieldValue Method...........................................................................................572.3.3.13.2 IAntenna::GetSectionCount Method ......................................................................................572.3.3.13.3 IAntenna::GetSection Method................................................................................................572.3.3.13.4 Example.................................................................................................................................58

2.3.3.14 IAntennaPatternSection Interface ...............................................................................................602.3.3.14.1 _IAntennaPatternValue Structure ..........................................................................................612.3.3.14.2 TypeDefs ...............................................................................................................................612.3.3.14.3 Enumerations.........................................................................................................................612.3.3.14.4 IAntennaPatternSection::GetOrientation Method ..................................................................612.3.3.14.5 IAntennaPatternSection::GetPatternSize Method .................................................................612.3.3.14.6 IAntennaPatternSection::GetPattern Method ........................................................................61

2.3.3.15 IEnumAntennas Interface ............................................................................................................622.3.3.15.1 Example.................................................................................................................................622.3.3.15.2 IEnumAntennas::Next Method...............................................................................................622.3.3.15.3 IEnumAntennas::Skip Method ...............................................................................................622.3.3.15.4 IEnumAntennas::Reset Method.............................................................................................632.3.3.15.5 IEnumAntennas::Clone Method.............................................................................................63

2.3.4 Coding Rules.....................................................................................................................................632.3.4.1 Serialization of All Parameters (Multithread) ...............................................................................632.3.4.2 Global Variables (Multithread) .....................................................................................................632.3.4.3 Read Access to External Files (Distributed Computing) .............................................................632.3.4.4 Performance (Multithread)...........................................................................................................632.3.4.5 Use of GetFieldValue Method (Multithread) ................................................................................632.3.4.6 Only One Thread for Calculations (Multithread) ..........................................................................642.3.4.7 Log File Generation (Multithread)................................................................................................642.3.4.8 Interaction with Add-Ins (Multithread)..........................................................................................64vi AT260_DRG_E0 Forsk 2007

Table of Contents3 General API .................................................................................... 673.1 Add-ins, Macros, and Scripts ................................................................................................................. 673.2 Add-in Tutorial........................................................................................................................................ 67

3.2.1 Step 1: Creating the Add-in Project .................................................................................................. 673.2.2 Step 2: Inserting and Configuring the Add-in Object ........................................................................ 68

3.2.2.1 Commands ................................................................................................................................. 703.2.2.2 Events......................................................................................................................................... 703.2.2.3 Connection.................................................................................................................................. 70

3.2.3 Step 3: Catching Events ................................................................................................................... 713.2.4 Step 4: Customizing Add-ins ............................................................................................................ 72

3.3 Script Tutorial ......................................................................................................................................... 723.3.1 Step 1: Writing a VBScript File ......................................................................................................... 723.3.2 Step 2: Testing the Script ................................................................................................................. 733.3.3 Step 3: Scheduling the Script ........................................................................................................... 733.3.4 Step 4: Debugging the Script ........................................................................................................... 753.3.5 Step 5: Error Management ............................................................................................................... 75

3.4 Macro Tutorial ........................................................................................................................................ 773.4.1 Adding Macros in Atoll...................................................................................................................... 773.4.2 Running a Macro .............................................................................................................................. 783.4.3 Saving a List of Macros .................................................................................................................... 78

3.5 Reference Guide .................................................................................................................................... 783.5.1 Atoll Object Model ............................................................................................................................ 79

3.5.1.1 Objects........................................................................................................................................ 793.5.1.2 Properties and Methods.............................................................................................................. 793.5.1.3 Global or Member Access Functions.......................................................................................... 80

3.5.2 Application Object ............................................................................................................................ 803.5.3 Documents Object ............................................................................................................................ 813.5.4 Document Object.............................................................................................................................. 813.5.5 TabularData Object .......................................................................................................................... 823.5.6 ChildFolder Object............................................................................................................................ 843.5.7 CoordSystem Object ........................................................................................................................ 843.5.8 Atoll Interfaces.................................................................................................................................. 85

3.5.8.1 IApplication Interface .................................................................................................................. 863.5.8.1.1 Application Property .............................................................................................................. 873.5.8.1.2 Parent Property ..................................................................................................................... 873.5.8.1.3 Active Property...................................................................................................................... 873.5.8.1.4 Documents Property ............................................................................................................. 873.5.8.1.5 Name Property ...................................................................................................................... 883.5.8.1.6 FullName Property ................................................................................................................ 883.5.8.1.7 Path Property ........................................................................................................................ 883.5.8.1.8 ActiveDocument Property ..................................................................................................... 893.5.8.1.9 WindowStatus Property ........................................................................................................ 893.5.8.1.10 StatusBar Property................................................................................................................ 903.5.8.1.11 Visible Property ..................................................................................................................... 903.5.8.1.12 Version Property ................................................................................................................... 913.5.8.1.13 Quit Method .......................................................................................................................... 913.5.8.1.14 LogMessage Method ............................................................................................................ 913.5.8.1.15 SetAddinInfo Method ............................................................................................................ 913.5.8.1.16 AddCommand Method .......................................................................................................... 92

3.5.8.2 IDocuments Interface.................................................................................................................. 923.5.8.2.1 _NewEnum Property ............................................................................................................. 923.5.8.2.2 Count Property ...................................................................................................................... 933.5.8.2.3 Item Property ........................................................................................................................ 943.5.8.2.4 Application Property .............................................................................................................. 943.5.8.2.5 Parent Property ..................................................................................................................... 943.5.8.2.6 Open Method ........................................................................................................................ 943.5.8.2.7 Add Method........................................................................................................................... 953.5.8.2.8 OpenFromDatabase Method ................................................................................................ 963.5.8.2.9 CloseAll Method .................................................................................................................... 973.5.8.2.10 SaveAll Method ..................................................................................................................... 97

3.5.8.3 IDocument Interface ................................................................................................................... 973.5.8.3.1 Application Property .............................................................................................................. 993.5.8.3.2 Parent Property ..................................................................................................................... 993.5.8.3.3 FullName Property ................................................................................................................ 993.5.8.3.4 Name Property ...................................................................................................................... 993.5.8.3.5 Path Property ...................................................................................................................... 1003.5.8.3.6 ReadOnly Property ............................................................................................................. 100 Forsk 2007 AT260_DRG_E0 vii

Developer Reference Guide3.5.8.3.7 Saved Property ....................................................................................................................1003.5.8.3.8 CoordSystemProjection Property ........................................................................................1003.5.8.3.9 CoordSystemDisplay Property.............................................................................................1013.5.8.3.10 CoordSystemInternal Property ............................................................................................1013.5.8.3.11 TransmissionUnit Property ..................................................................................................1013.5.8.3.12 ReceptionUnit Property........................................................................................................1013.5.8.3.13 DistanceUnit Property..........................................................................................................1023.5.8.3.14 Close Method.......................................................................................................................1023.5.8.3.15 FilePrint Method...................................................................................................................1023.5.8.3.16 Save Method........................................................................................................................1023.5.8.3.17 Refresh Method ...................................................................................................................1033.5.8.3.18 Archive Method....................................................................................................................1033.5.8.3.19 Run Method .........................................................................................................................1033.5.8.3.20 SetConfig Method ................................................................................................................1043.5.8.3.21 Import Method......................................................................................................................1043.5.8.3.22 GetRecords Method.............................................................................................................1043.5.8.3.23 Redraw Method ...................................................................................................................1053.5.8.3.24 CenterMapOn Method .........................................................................................................1053.5.8.3.25 GetRootFolder Method ........................................................................................................1053.5.8.3.26 GetSortedSignals Method....................................................................................................1063.5.8.3.27 GetSortedServers Method ...................................................................................................107

3.5.8.4 IDocument2 Interface ................................................................................................................1083.5.8.4.1 RunPathloss Method ...........................................................................................................1083.5.8.4.2 GetService Property ............................................................................................................108

3.5.8.5 IDocument3 Interface ................................................................................................................1093.5.8.5.1 ExportConfig Method ...........................................................................................................109

3.5.8.6 IDocument4 Interface ................................................................................................................1093.5.8.6.1 GetCommandDefaults Property...........................................................................................1103.5.8.6.2 InvokeCommand Property ...................................................................................................1103.5.8.6.3 RadiatedPowerUnit Property ...............................................................................................1103.5.8.6.4 AntennaGainUnit Property...................................................................................................1103.5.8.6.5 HeightOffsetUnit Property....................................................................................................111

3.5.8.7 IResultFileProvider Interface .....................................................................................................1113.5.8.7.1 Build Method........................................................................................................................111

3.5.8.8 ITabularData Interface...............................................................................................................1123.5.8.8.1 ColumnCount Property ........................................................................................................1123.5.8.8.2 RowCount Property .............................................................................................................1123.5.8.8.3 Edit Method..........................................................................................................................1133.5.8.8.4 AddNew Method ..................................................................................................................1133.5.8.8.5 Update Method ....................................................................................................................1133.5.8.8.6 Delete Method .....................................................................................................................1133.5.8.8.7 GetValue Method.................................................................................................................1143.5.8.8.8 SetValue Method .................................................................................................................1153.5.8.8.9 GetPrimaryKey Method .......................................................................................................1173.5.8.8.10 FindPrimaryKey Method ......................................................................................................1173.5.8.8.11 Find Method.........................................................................................................................1173.5.8.8.12 GetFormattedValue Method ................................................................................................1183.5.8.8.13 Reading Pathloss Matrices ..................................................................................................1183.5.8.8.14 Editing Computation or Focus Zones ..................................................................................1203.5.8.8.15 Editing Repeaters ................................................................................................................1223.5.8.8.16 Reading Antenna Signatures...............................................................................................1223.5.8.8.17 Accessing Transmitter EIRPs and Antenna Diagrams ........................................................1223.5.8.8.18 Reading Data Tab Folders (Simulations).............................................................................1233.5.8.8.19 Reading Data Tab Folders (CW Measurements and Test Mobile Data) .............................124

3.5.8.9 ITabularData2 Interface.............................................................................................................1253.5.8.9.1 CancelUpdate Method .........................................................................................................1263.5.8.9.2 ColumnNumber Property .....................................................................................................1263.5.8.9.3 CanEdit Property .................................................................................................................1263.5.8.9.4 CanAddNew Property ..........................................................................................................1263.5.8.9.5 CanFilterSort Property .........................................................................................................1263.5.8.9.6 Filter Property ......................................................................................................................1273.5.8.9.7 Filter Property ......................................................................................................................1273.5.8.9.8 Sort Property........................................................................................................................1273.5.8.9.9 Sort Property........................................................................................................................1283.5.8.9.10 GetOriginalValue Property...................................................................................................1283.5.8.9.11 RowStatus Property.............................................................................................................128

3.5.8.10 IPropertyContainer Interface .....................................................................................................1283.5.8.10.1 Get Property ........................................................................................................................129viii AT260_DRG_E0 Forsk 2007

Table of Contents3.5.8.10.2 Set Property ........................................................................................................................ 1293.5.8.11 IChildFolder Interface ............................................................................................................... 129

3.5.8.11.1 Application Property ............................................................................................................ 1303.5.8.11.2 Parent Property ................................................................................................................... 1303.5.8.11.3 Name Property .................................................................................................................... 1303.5.8.11.4 Count Property .................................................................................................................... 1313.5.8.11.5 Item Property ...................................................................................................................... 1313.5.8.11.6 _NewEnum Property ........................................................................................................... 1313.5.8.11.7 Visible Property ................................................................................................................... 1323.5.8.11.8 Selected Property ............................................................................................................... 1323.5.8.11.9 Export Method..................................................................................................................... 1333.5.8.11.10 CentreOnMap Method ........................................................................................................ 1333.5.8.11.11 Redraw Method................................................................................................................... 134

3.5.8.12 IChildFolder2 Interface ............................................................................................................. 1343.5.8.12.1 AddChild Property ............................................................................................................... 1343.5.8.12.2 Remove Method.................................................................................................................. 1343.5.8.12.3 Position Property................................................................................................................. 1353.5.8.12.4 Object Property ................................................................................................................... 1353.5.8.12.5 Dispatch Property ............................................................................................................... 1353.5.8.12.6 ObjectKind Property ............................................................................................................ 135

3.5.8.13 IChildFolder3 Interface ............................................................................................................. 1363.5.8.13.1 GetProperty Property .......................................................................................................... 1363.5.8.13.2 SetProperty Method ............................................................................................................ 137

3.5.8.14 IClutter Interface ....................................................................................................................... 1373.5.8.14.1 Source Property .................................................................................................................. 1373.5.8.14.2 ClassAttributes Property ..................................................................................................... 1373.5.8.14.3 DefaultAttributes Property ................................................................................................... 138

3.5.8.15 ISimulationsGroup Interface ..................................................................................................... 1383.5.8.15.1 Source Property .................................................................................................................. 1393.5.8.15.2 Statistics Property ............................................................................................................... 1393.5.8.15.3 MeanSimulation Property.................................................................................................... 1393.5.8.15.4 StdDevSimulation Property ................................................................................................. 1393.5.8.15.5 Example .............................................................................................................................. 140

3.5.8.16 ISimulation Interface ................................................................................................................. 1403.5.8.16.1 Source Property ................................................................................................................. 1403.5.8.16.2 Statistics Property ............................................................................................................... 1403.5.8.16.3 Cells Property ..................................................................................................................... 1403.5.8.16.4 Sites Property ..................................................................................................................... 1403.5.8.16.5 Mobiles Property ................................................................................................................. 1413.5.8.16.6 Example .............................................................................................................................. 141

3.5.8.17 IDispCoordSystem Interface..................................................................................................... 1413.5.8.17.1 Code Property ..................................................................................................................... 1413.5.8.17.2 ConvertCoordsTo Method................................................................................................... 1423.5.8.17.3 Datum Property ................................................................................................................... 1443.5.8.17.4 DatumName Property ......................................................................................................... 1443.5.8.17.5 Description Property ........................................................................................................... 1443.5.8.17.6 Ellipsoid Property ................................................................................................................ 1453.5.8.17.7 EllipsoidName Property....................................................................................................... 1453.5.8.17.8 Name Property .................................................................................................................... 1453.5.8.17.9 Pick Method ........................................................................................................................ 1453.5.8.17.10 ProjMethod Property ........................................................................................................... 1463.5.8.17.11 ProjParameter Property ...................................................................................................... 1463.5.8.17.12 SetDatum Method ............................................................................................................... 1473.5.8.17.13 SetProjection Method.......................................................................................................... 1473.5.8.17.14 Unit Property ....................................................................................................................... 147

3.5.8.18 IApplicationKeyRef Interface .................................................................................................... 1483.5.8.18.1 IsFixedKey Method ............................................................................................................. 1483.5.8.18.2 IsNetworkKey Method ......................................................................................................... 1483.5.8.18.3 GetFskKeyRef Method........................................................................................................ 1493.5.8.18.4 Example .............................................................................................................................. 149

3.5.8.19 ITraffic Interface........................................................................................................................ 1493.5.8.19.1 Source Property .................................................................................................................. 1503.5.8.19.2 ScenarioProvider Property .................................................................................................. 1503.5.8.19.3 Example .............................................................................................................................. 150

3.5.8.20 ITrafficScenarioProvider Interface ............................................................................................ 1513.5.8.20.1 GetMeanSize Property........................................................................................................ 1513.5.8.20.2 Create Property................................................................................................................... 151

3.5.8.21 ITrafficPerEnvironment Interface .............................................................................................. 152 Forsk 2007 AT260_DRG_E0 ix

Developer Reference Guide3.5.8.21.1 Source Property...................................................................................................................1523.5.8.21.2 ClassAttributes Property ......................................................................................................1523.5.8.21.3 DefaultAttributes Property....................................................................................................152

3.5.9 Outgoing Interfaces.........................................................................................................................1553.5.9.1 _IApplicationEvents Interface ....................................................................................................155

3.5.9.1.1 WillQuitApp Method .............................................................................................................1563.5.9.1.2 DocumentOpenComplete Method .......................................................................................1563.5.9.1.3 WillCloseDocument Method ................................................................................................1563.5.9.1.4 WillSaveDocument Method .................................................................................................1563.5.9.1.5 DocumentSaveComplete Method........................................................................................1563.5.9.1.6 DocumentNewComplete Method .........................................................................................1573.5.9.1.7 WillRefreshDocument Method .............................................................................................1573.5.9.1.8 RefreshDocumentComplete Method ...................................................................................1573.5.9.1.9 WillArchiveDocument Method..............................................................................................1573.5.9.1.10 ArchiveDocumentComplete Method ....................................................................................1573.5.9.1.11 WillRun Method ...................................................................................................................1583.5.9.1.12 RunComplete Method..........................................................................................................1583.5.9.1.13 LicenceAcquireComplete .....................................................................................................1583.5.9.1.14 LicenceReleaseComplete....................................................................................................159

3.5.9.2 IAddin Interface .........................................................................................................................1593.5.9.2.1 Connecting an External Tool to a Running Session of Atoll ................................................1593.5.9.2.2 Adding Commands ..............................................................................................................1603.5.9.2.3 OnConnection Method.........................................................................................................1603.5.9.2.4 OnDisconnection Method ....................................................................................................160

3.5.10 Rules, Contracts and Advices .........................................................................................................1613.5.10.1 Error Handling ...........................................................................................................................1613.5.10.2 Automatic Reference Counting .................................................................................................1613.5.10.3 MFC Support Considerations ....................................................................................................161

3.5.10.3.1 BSTR and VARIANT Types .................................................................................................1613.5.10.3.2 Resource Access.................................................................................................................161

3.5.10.4 Shutting Down Atoll ...................................................................................................................1613.5.11 Enumerations ..................................................................................................................................161

3.5.11.1 AtoSaveStatus...........................................................................................................................1613.5.11.2 AtoSaveChanges ......................................................................................................................1613.5.11.3 AtoRefreshPriority .....................................................................................................................1623.5.11.4 AtoArchiveStatus .......................................................................................................................1623.5.11.5 AtoWindowStatus ......................................................................................................................1623.5.11.6 AtoLogType ...............................................................................................................................1623.5.11.7 AtoCompareOp .........................................................................................................................1623.5.11.8 AtoTransmissionUnit .................................................................................................................1623.5.11.9 AtoReceptionUnit ......................................................................................................................1633.5.11.10 AtoDistanceUnit.........................................................................................................................1633.5.11.11 AtoRadiatedPowerUnit ..............................................................................................................1633.5.11.12 AtoAntennaGainUnit..................................................................................................................1633.5.11.13 AtoHeightOffsetUnit...................................................................................................................1633.5.11.14 AtoRootType .............................................................................................................................1633.5.11.15 AtoRowFilter ..............................................................................................................................1633.5.11.16 AtoRowStatus............................................................................................................................1643.5.11.17 GeographicUnit .........................................................................................................................1643.5.11.18 ProjectionMethod ......................................................................................................................1643.5.11.19 ProjParameterIndices ................................................................................................................165

3.5.12 Raster Data API ..............................................................................................................................1653.5.12.1 Raster Data API Structures .......................................................................................................165

3.5.12.1.1 GEOPOINT Structure ..........................................................................................................1653.5.12.1.2 GEOSIZE Structure .............................................................................................................1653.5.12.1.3 GEORECT Structure ...........................................................................................................1653.5.12.1.4 GEOGRID Structure ............................................................................................................1663.5.12.1.5 RASTERBUFFER Structure ................................................................................................166

3.5.12.2 Enumerations ............................................................................................................................1663.5.12.3 IGeoCoverage Interface ............................................................................................................167

3.5.12.3.1 get_DataType Method .........................................................................................................1673.5.12.3.2 get_NoDataValue Method ...................................................................................................1673.5.12.3.3 get_BoundingBox Method ...................................................................................................1683.5.12.3.4 get_OptimalResolution Method ...........................................................................................1683.5.12.3.5 Rasterize Method.................................................................................................................168

3.5.12.4 IGeoRaster Interface .................................................................................................................1693.5.12.4.1 get_Grid Method ..................................................................................................................1693.5.12.4.2 ReadDataBlock Method.......................................................................................................170x AT260_DRG_E0 Forsk 2007

Table of Contents3.5.12.5 IColorTable Interface ................................................................................................................ 1703.5.12.5.1 get_ColorCount Method ...................................................................................................... 1703.5.12.5.2 get_Colors Method.............................................................................................................. 171

3.5.12.6 Optional Interfaces For The GeoRaster Object ........................................................................ 1713.5.12.6.1 IActiveMapObject Method ................................................................................................... 1713.5.12.6.2 QueryHitPoint Method......................................................................................................... 1713.5.12.6.3 OnWindowMessage Method ............................................................................................... 1713.5.12.6.4 QueryDataTip Method......................................................................................................... 172

3.5.12.7 IContextMenu Interface ............................................................................................................ 1723.5.12.7.1 GetCommandString Method ............................................................................................... 1733.5.12.7.2 QueryContextMenu Method ................................................................................................ 1733.5.12.7.3 InvokeCommand Method .................................................................................................... 173

3.5.12.8 Other Interfaces ........................................................................................................................ 1743.6 Appendix .............................................................................................................................................. 174

3.6.1 Predictions Tabular Data ................................................................................................................ 1743.6.2 Zones Tabular Data........................................................................................................................ 1753.6.3 Best Signal Export Add-in .............................................................................................................. 175

4 Basic AFP API .............................................................................. 1794.1 Introduction .......................................................................................................................................... 1794.2 AFP Model Tutorial .............................................................................................................................. 1794.3 Basic Definitions................................................................................................................................... 179

4.3.1 Resource Number .......................................................................................................................... 1794.3.2 Resource Group ............................................................................................................................. 1794.3.3 Grouping Scheme .......................................................................................................................... 1794.3.4 MAL Mobile Allocation List .......................................................................................................... 1794.3.5 TRG TRX Group.......................................................................................................................... 179

4.3.5.1 Examples .................................................................................................................................. 1804.3.5.1.1 Normal Cell Configuration ................................................................................................... 1804.3.5.1.2 Concentric Cell Configuration ............................................................................................. 180

4.4 Various Roles of Grouping Schemes ................................................................................................... 1804.5 Data Exchange..................................................................................................................................... 180

4.5.1 Nested Interfaces and Arrays as Means ........................................................................................ 1804.5.2 Elements Implemented by Atoll ...................................................................................................... 181

4.5.2.1 IAfpNetworkData Interface........................................................................................................ 1814.5.2.2 IAssignmentPlan Interface........................................................................................................ 1814.5.2.3 IRW_AssignmentPlan:IAssignmentPlan Interface.................................................................... 1814.5.2.4 IGroupingScheme Interface...................................................................................................... 1814.5.2.5 IDynamicGroupingScheme:IGroupingScheme Interface.......................................................... 1814.5.2.6 ITrg Interface ............................................................................................................................ 1814.5.2.7 IFrequencyBand Interface ........................................................................................................ 1814.5.2.8 ITrgSeparations Interface ......................................................................................................... 1814.5.2.9 IInterfMatrix Interface................................................................................................................ 1814.5.2.10 IAFPProgress Interface ............................................................................................................ 182

4.5.3 Elements Implemented by The Model ............................................................................................ 1824.5.3.1 IAfpModel Interface................................................................................................................... 1824.5.3.2 IPlanGenerator Interface .......................................................................................................... 1824.5.3.3 IAFPConfigure Interface (Optional) .......................................................................................... 182

4.6 Reference Guide .................................................................................................................................. 1824.6.1 Enumerations and Structures ......................................................................................................... 182

4.6.1.1 ALLOCATION_TYPE................................................................................................................ 1824.6.1.2 ALLOCATION_OPTIONS (Not Used) ...................................................................................... 1824.6.1.3 RESOURCE_TYPE .................................................................................................................. 1824.6.1.4 ASSIGNMENT_MODE ............................................................................................................. 1834.6.1.5 ASSIGNMENT_STATE ............................................................................................................ 183

4.6.1.5.1 TO_ASSIGN and FROZEN States...................................................................................... 1834.6.1.6 HOPPING_MODE .................................................................................................................... 1834.6.1.7 AFP_RELATION_TYPE ........................................................................................................... 1834.6.1.8 QUALITY_METRIC (Not Used) ................................................................................................ 1844.6.1.9 AFP_BASE_CONFIG ............................................................................................................... 184

4.6.2 Interfaces Implemented by Atoll ..................................................................................................... 1844.6.2.1 IAfpNetworkData Interface........................................................................................................ 184

4.6.2.1.1 IAfpNetworkData::GetTRGCount Method ........................................................................... 1844.6.2.1.2 IAfpNetworkData::GetFirstTRG Method.............................................................................. 1844.6.2.1.3 IAfpNetworkData::GetTRG Method..................................................................................... 1854.6.2.1.4 IAfpNetworkData::GetSeparations Method ......................................................................... 1854.6.2.1.5 IAfpNetworkData::GetCurrentPlan Method ......................................................................... 185

4.6.2.2 IAssignmentPlan Interface........................................................................................................ 185 Forsk 2007 AT260_DRG_E0 xi

Developer Reference Guide4.6.2.2.1 IAssignmentPlan::GetResource Method..............................................................................1854.6.2.2.2 IAssignmentPlan::GetTrxCount Method ..............................................................................1864.6.2.2.3 IAssignmentPlan::GetTrxNumber Method ...........................................................................1864.6.2.2.4 IAssignmentPlan::GetTrxIndex Method ...............................................................................1864.6.2.2.5 IAssignmentPlan::GetTrxNumbers Method .........................................................................1874.6.2.2.6 IAssignmentPlan::CreateClone Method...............................................................................1874.6.2.2.7 IAssignmentPlan::GetMALScheme Method ........................................................................1874.6.2.2.8 IAssignmentPlan::GetAssignmentState Method..................................................................187

4.6.2.3 IRW_AssignmentPlan:IAssignmentPlan Interface ....................................................................1884.6.2.3.1 IRW_AssignmentPlan::AddTrxs Method .............................................................................1884.6.2.3.2 IRW_AssignmentPlan::RemoveTrx Method ........................................................................1884.6.2.3.3 IRW_AssignmentPlan::SetResource Method ......................................................................188

4.6.2.4 IGroupingScheme Interface ......................................................................................................1884.6.2.4.1 IGroupingScheme::GetGroupingSchemeID Method ...........................................................1884.6.2.4.2 IGroupingScheme::GetGroupCount Method .......................................................................1894.6.2.4.3 IGroupingScheme::GetGroupSize Method ..........................................................................1894.6.2.4.4 IGroupingScheme::GetResourceNumbers Method .............................................................1894.6.2.4.5 IGroupingScheme::Contains Method...................................................................................189

4.6.2.5 IDynamicGroupingScheme: IGroupingScheme Interface .........................................................1904.6.2.5.1 IDynamicGroupingScheme::AddGrp Method ......................................................................1904.6.2.5.2 IDynamicGroupingScheme::SetGrp Method .......................................................................1904.6.2.5.3 IDynamicGroupingScheme::DeleteGrp Method ..................................................................190

4.6.2.6 ITrg Interface .............................................................................................................................1904.6.2.6.1 ITrg::GetIndx Method...........................................................................................................1904.6.2.6.2 ITrg::GetTrxType Method ....................................................................................................1914.6.2.6.3 ITrg::ContainsBroadcastChannel Method............................................................................1914.6.2.6.4 ITrg::GetGroupingScheme Method......................................................................................1914.6.2.6.5 ITrg::GetFrequencyBand Method ........................................................................................1914.6.2.6.6 ITrg::GetDemand Method ....................................................................................................1924.6.2.6.7 ITrg::GetTrafficLoad Method................................................................................................1924.6.2.6.8 ITrg::GetDLTimeSlotUseRatio Method ................................................................................1924.6.2.6.9 ITrg::GetCostWeightingFactor Method ................................................................................1924.6.2.6.10 ITrg::GetHoppingMode Method ...........................................................................................1924.6.2.6.11 ITrg::GetAssignmentMode Method ......................................................................................1934.6.2.6.12 ITrg::GetMALSize Method ...................................................................................................1934.6.2.6.13 ITrg::IsInRelation Method ....................................................................................................1934.6.2.6.14 ITrg::GetTrgRelationCount Method .....................................................................................1934.6.2.6.15 ITrg::GetTrgRelation Method ...............................................................................................1944.6.2.6.16 ITrg::GetTransmitter Method ...............................................................................................1944.6.2.6.17 ITrg::GetQualityThreshold Method ......................................................................................1944.6.2.6.18 ITrg::GetProbabilityThreshold Method .................................................................................194

4.6.2.7 IFrequencyBand Interface .........................................................................................................1954.6.2.7.1 IFrequencyBand::GetMultiPlexingFactor Method ................................................................1954.6.2.7.2 IFrequencyBand::GetCoherenceBandWidth Method ..........................................................1954.6.2.7.3 IFrequencyBand::GetAdjascentSuppression Method ..........................................................195

4.6.2.8 ITrgSeparations Interface ..........................................................................................................1954.6.2.8.1 ITrgSeparations::GetSeparation Method .............................................................................1954.6.2.8.2 ITrgSeparations::GetDefaultSeparation Method..................................................................1964.6.2.8.3 ITrgSeparations::GetRelationsCount Method......................................................................1964.6.2.8.4 ITrgSeparations::GetRelation Method .................................................................................196

4.6.2.9 IInterfMatrix Interface ................................................................................................................1974.6.2.9.1 IInterfMatrix::GetHistogramSize Method..............................................................................1974.6.2.9.2 IInterfMatrix::GetInterferingHistogram Method ....................................................................1974.6.2.9.3 IInterfMatrix::GetInterferingProbability Method ....................................................................1974.6.2.9.4 IInterfMatrix::GetInterfererCount Method.............................................................................1984.6.2.9.5 IInterfMatrix::GetInterferers Method.....................................................................................1984.6.2.9.6 IInterfMatrix::GetVictimCount Method..................................................................................1984.6.2.9.7 IInterfMatrix::GetVictims Method .........................................................................................1984.6.2.9.8 IInterfMatrix::GetInterfererHistogram Method ......................................................................199

4.6.2.10 IAFPProgress Interface .............................................................................................................1994.6.2.10.1 IAFPProgress::StartProgressReport Method.......................................................................1994.6.2.10.2 IAFPProgress::OnProgress Method ....................................................................................1994.6.2.10.3 IAFPProgress::Display Method............................................................................................1994.6.2.10.4 IAFPProgress::DisplayLogInfo Method................................................................................2004.6.2.10.5 IAFPProgress::DisplayLogWarning Method ........................................................................2004.6.2.10.6 IAFPProgress::DisplayLogError Method..............................................................................200

4.6.3 Interfaces Implemented by The Model............................................................................................2004.6.3.1 IAfpModel Interface ...................................................................................................................200xii AT260_DRG_E0 Forsk 2007

Table of Contents4.6.3.1.1 IAfpModel::GetPlanGenerator Method................................................................................ 2004.6.3.2 IPlanGenerator Interface .......................................................................................................... 200

4.6.3.2.1 IPlanGenerator::Run Method .............................................................................................. 2014.6.3.2.2 IPlanGenerator::Improve Method........................................................................................ 201

4.6.3.3 IAfpConfigure Interface............................................................................................................. 2014.6.3.3.1 IAfpConfigure::Configure Method ....................................................................................... 201

4.7 Using the AFP Interfaces ..................................................................................................................... 2024.7.1 The Basic main() of an AFP ......................................................................................................... 2024.7.2 Working with Network Data ............................................................................................................ 2034.7.3 Access to TRGs ............................................................................................................................. 2044.7.4 Access to Separations Constraints ................................................................................................ 2044.7.5 Access to Grouping Schemes ........................................................................................................ 2054.7.6 Working with Interference Matrices ................................................................................................ 206

4.7.6.1 Example.................................................................................................................................... 2064.7.7 Working with Several Assignment Plans ........................................................................................ 2064.7.8 Reading and Writing Resources..................................................................................................... 2084.7.9 TRX Manipulations ......................................................................................................................... 2094.7.10 Specific Case of SFH ..................................................................................................................... 210

5 Advanced AFP API ....................................................................... 2155.1 Multiple Interface System..................................................................................................................... 2155.2 Read/Write Capabilities and GUI Integration ....................................................................................... 215

5.2.1 New Capabilities............................................................................................................................. 2155.2.2 Required Implementation ............................................................................................................... 2155.2.3 IResourceCollection, IAssignmentPlan2, IRW_AssignmentPlan2 Interfaces ................................ 216

5.3 Scenarios Support................................................................................................................................ 2165.4 New Services Provided by INetworkData2 .......................................................................................... 216

5.4.1 Temporary Method: INetworkData2::ReadIMFile() ........................................................................ 2165.5 AFP API Code...................................................................................................................................... 216 Forsk 2007 AT260_DRG_E0 xiii

Developer Reference Guidexiv AT260_DRG_E0 Forsk 2007

List of FiguresList of Figures

Figure 2.1: New Project Dialog .................................................................................................................................... 23Figure 2.2: Atoll ATL Project Wizard............................................................................................................................ 23Figure 2.3: Add Class Dialog ....................................................................................................................................... 24Figure 2.4: Atoll ATL Propagation Model Object Wizard ............................................................................................. 25Figure 2.5: Add Property.............................................................................................................................................. 26Figure 2.6: Add Property Wizard.................................................................................................................................. 26Figure 2.7: Adding a Property Page............................................................................................................................. 27Figure 2.8: ATL Property Page Wizard ........................................................................................................................ 28Figure 3.1: New Project Dialog .................................................................................................................................... 67Figure 3.2: Atoll ATL Project Wizard............................................................................................................................ 68Figure 3.3: Add Class Dialog ....................................................................................................................................... 69Figure 3.4: Atoll ATL Add-in Object Wizard 1 .............................................................................................................. 69Figure 3.5: Atoll ATL Add-in Object Wizard 2 .............................................................................................................. 70Figure 3.6: Add-in Example 1 ...................................................................................................................................... 71Figure 3.7: Add-in Example 2 ...................................................................................................................................... 72Figure 3.8: Scheduled Tasks Wizard 1 ........................................................................................................................ 74Figure 3.9: Scheduled Tasks Wizard 2 ........................................................................................................................ 74Figure 3.10: Scheduled Tasks Wizard 3 ........................................................................................................................ 74Figure 3.11: Atoll Tutorial............................................................................................................................................... 75Figure 3.12: Scheduled Tasks ....................................................................................................................................... 75Figure 3.13: Adding Macros in Atoll ............................................................................................................................... 77Figure 3.14: Atoll Object Model...................................................................................................................................... 79 Forsk 2007 AT260_DRG_E0 xv

Developer Reference Guidexvi AT260_DRG_E0 Forsk 2007

Introduction

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

Chapter 1

18 AT260_DRG_E0 Forsk 2007

Developer Reference Guide

Chapter 1: Introduction1 Introduction1.1 Getting Started

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

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.

1.2 PrerequisitesThe Atoll Development Toolkit is based on a set of COM interfaces allowing communication between Atoll and externalmodules. 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, someenhanced support is available for Visual C++ .NET and ActiveX Template Library (ATL) users. If you are not familiar withthis environment, especially with the very specific programming style of ATL, we recommend you to go through the ATLtutorial provided with Visual C++ .NET.

To have the Atoll object wizard correctly installed inside Visual C++ .NET, you must install (or reinstall) Atoll after VisualC++ .NET. Furthermore, if you consider developing a parameterised model, you must be familiar with some additionalCOM 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 ExtensionsThere are currently five extension types available:

Propagation Models Add-ins Macros Scripts Automatic Frequency Planning Models

1.3.1 Propagation ModelsAtoll delegates propagation calculations to external dynamic libraries registered on the computer. The software incorpo-rates 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, thisdocument provides examples using Microsoft Visual C++ only.

For further information, please refer to chapter 2 "Propagation API".

1.3.2 Add-insTo facilitate extensions in Atoll by external developers, Forsk has introduced a technology greatly inspired from the Micro-soft 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 canbe built using any COM-compliant C++ development environment. For simplicity and clarity, this document provides exam-ples 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. Thescreenshots in this document only refer to Visual C++ .NET. If Visual C++ 6.0 is installed prior to Atoll, quite similar wizarddialogs are also available in Visual C++ 6.0. If you require assistance specifically regarding Visual C++ 6.0, please contactthe Forsk Support Team. Forsk 2007 AT260_DRG_E0 19

Developer Reference Guide1.3.3 MacrosMacros allow the automation of tasks in Atoll without requiring special C++ programming skills. Its possible for a macroto 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 ScriptsScripts allow the automation of tasks when no interaction with the user is needed. Scripts are specially useful for sched-uling 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 ModelsAutomatic Frequency Planning is a very important issue, which is addressed by this type of models. The