Developer Reference Guide

RF planning
View more...
   EMBED

Share

Preview only show first 6 pages with water mark for full document please download

Transcript

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, People’s Republic of China  L « ¬ www.forsk.com [email protected] [email protected] [email protected] +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 [email protected] [email protected] +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 [email protected] +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 API’s. 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 API’s. 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 API’s 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 v 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 x 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 1 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. It’s 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 Atoll’s 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 2 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 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::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 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) 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 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(&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, public CComCoClass, public IObjectWithSiteImpl, public IDispatchImpl, 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 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 > 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 allResults; allResults.resize(nResolutions); for (int iRes=0;iResSetStatusText(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 *pRet; CComObject::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 window’s 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 don’t use this value because the result is undefined. “TYPE” Private usage of the dev. Please don’t use this value because the result is undefined. “CODE_SERVICE” Private usage of the dev. Please don’t 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 m_srv; GetSite(IID_IServiceProvider,(void**)&m_srv); CComPtr 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 don’t use this value because the result is undefined. “TYPE” Private usage of the dev. Please don’t use this value because the result is undefined. “CODE_SERVICE” Private usage of the dev. Please don’t 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 Atoll’s General API. Developer Reference Guide 66 AT260_DRG_E0 © Forsk 2007 Chapter 3: General API 3 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 user’s 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 object’s 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 Atoll’s 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 document’s 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 Atoll’s 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 Forsk’s 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 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) P HRESULT ActiveDocument(IDocument**) P HRESULT AddCommand(BSTR, BSTR, VARIANT_BOOL, long, VARIANT_BOOL*) M HRESULT Application(IApplication**) P HRESULT Documents(IDocuments**) P HRESULT FullName(BSTR*) P HRESULT LogMessage(BSTR, AtoLogType) M HRESULT Name(BSTR* ) P HRESULT Parent(IApplication**) P HRESULT Path(BSTR*) P HRESULT Quit(AtoSaveChanges, AtoSaveStatus*) M HRESULT SetAddinInfo(long, LPDISPATCH, long, long) M HRESULT StatusBar(BSTR) P HRESULT Version(BSTR*) P HRESULT Visible(VARIANT_BOOL*) HRESULT Visible(VARIANT_BOOL) P HRESULT WindowStatus(AtoWindowStatus*) HRESULT WindowStatus(AtoWindowStatus) P 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 user’s 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*) P HRESULT Add(BSTR, IDocument**) M HRESULT Application(IApplication**) P HRESULT CloseAll(AtoSaveChanges,AtoSaveStatus*) M HRESULT Count(LONG*) P HRESULT Item(VARIANT, IDocument**) P HRESULT Open(BSTR, VARIANT_BOOL, IDocument **) M HRESULT OpenFromDatabase(VARIANT, BSTR, IDocument**) M HRESULT Parent(IApplication**) P HRESULT SaveAll(); M _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 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(";"), &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 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**) P HRESULT Archive(AtoArchiveStatus*) M HRESULT CenterMapOn(double*, double*) M HRESULT Close(AtoSaveChanges, AtoSaveStatus*) M HRESULT CoordSystemDisplay(IDispCoordSystem**) HRESULT CoordSystemDisplay(IDispCoordSystem*) P HRESULT CoordSystemInternal(IDispCoordSystem**) P HRESULT CoordSystemProjection(IDispCoordSystem**) HRESULT CoordSystemProjection(IDispCoordSystem*) P HRESULT DistanceUnit(AtoDistanceUnit*) HRESULT DistanceUnit(AtoDistanceUnit) P HRESULT FilePrint() M HRESULT FullName(BSTR*) P HRESULT GetRecords(BSTR, VARIANT_BOOL, ITabularData**) M HRESULT GetRootFolder(AtoRootType,IChildFolder**) M AT260_DRG_E0 © Forsk 2007 Chapter 3: General API 3.5.8.3.1 HRESULT Import(BSTR) M HRESULT Name(BSTR*) P HRESULT Parent(IApplication**) P HRESULT Path(BSTR*) P HRESULT ReadOnly(VARIANT_BOOL*) P HRESULT ReceptionUnit(AtoReceptionUnit*) HRESULT ReceptionUnit(AtoReceptionUnit) P HRESULT Redraw(); M HRESULT Refresh(AtoRefreshPriority) M HRESULT Run(VARIANT_BOOL) M HRESULT Save(BSTR) M HRESULT Saved(VARIANT_BOOL*) P HRESULT SetConfig(BSTR) M HRESULT TransmissionUnit(AtoTransmissionUnit *) HRESULT TransmissionUnit(AtoTransmissionUnit) P 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 document’s full path name with the extension. HRESULT FullName(BSTR *pVal); Parameters pVal: Address of string that receives the document’s 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 document’s 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 document’s name. Return Values S_OK. E_POINTER, if pVal is NULL. 3.5.8.3.5 Path Property Read-only property that gets the document’s path. HRESULT Path(BSTR *pVal); Parameters pVal: Address of string that receives the document’s 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 document’s 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 document’s 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, you’d 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, you’d 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 [email protected]). 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 [email protected]). 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) M HRESULT GetService (BSTR, IDispatch**) P 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) M 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); P HRESULT InvokeCommand([in] const BSTR bstrCommandName, [in, unique, defaultvalue(NULL)] IPropertyContainer *pParameters, [out, retval] IPropertyContainer **ppResults); P HRESULT RadiatedPowerUnit([out, retval] enum AtoRadiatedPowerUnit *pVal); HRESULT RadiatedPowerUnit([in] enum AtoRadiatedPowerUnit aNewVal); P HRESULT AntennaGainUnit([out, retval] enum AtoAntennaGainUnit *pVal); HRESULT AntennaGainUnit([in] enum AtoAntennaGainUnit aNwVal); P 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 P 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*) M 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 M HRESULT AddNew() HRESULT ColumnCount(long*) P HRESULT Delete(long) M HRESULT Edit(long) M HRESULT long*) 3.5.8.8.1 Property (P) Method (M) Function Find(long, VARIANT, AtoCompareOp, VARIANT, M HRESULT FindPrimaryKey(VARIANT val, long*) M HRESULT GetFormattedValue(long, VARIANT, BSTR *) M HRESULT GetPrimaryKey(long, VARIANT*); M HRESULT GetValue(long, VARIANT, VARIANT*) M HRESULT RowCount(long*) P HRESULT SetValue(VARIANT, VARIANT) M HRESULT Update(long*); M 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 column’s 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 Don’t 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 Don’t forget to call this method before a call to SetValue and to call Update to end the initialisation of the record’s 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 = L“TXLOSSES”; 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 site’s 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 // We’ll 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_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 repeater’s 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() M HRESULT ColumnNumber([in] VARIANT vColName, [out, retval] long *pCol) P HRESULT CanEdit([out, retval] VARIANT_BOOL *pVal) P HRESULT CanAddNew([out, retval] VARIANT_BOOL *pVal) P HRESULT CanFilterSort([out, retval] VARIANT_BOOL *pVal) P HRESULT Filter([in] VARIANT vCriteria) HRESULT Filter([out, retval] VARIANT *pvCriteria) P HRESULT Sort([in] VARIANT vCriteria) HRESULT Sort([out, retval] VARIANT *pvCriteria) P AT260_DRG_E0 125 Developer Reference Guide 3.5.8.9.1 HRESULT GetOriginalValue([in] long iRow, [in] VARIANT iCol, [out, retval] VARIANT *pVal) P HRESULT RowStatus([in] long iRow, [out, retval] enum AtoRowStatus *pVal) P 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); P AT260_DRG_E0 © Forsk 2007 Chapter 3: General API HRESULT Set([in] const BSTR bstrName, [in] const VARIANT varValue); 3.5.8.10.1 M 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) P HRESULT Application(IApplication**) P HRESULT CentreOnMap() M HRESULT Count(long*) P HRESULT Export(BSTR, IDispCoordSystem*, BSTR) M HRESULT Name(BSTR*) HRESULT Name(BSTR) P HRESULT Item(VARIANT idx, IChildFolder**) P HRESULT Parent(VARIANT*) P HRESULT Redraw() M HRESULT Selected(VARIANT_BOOL*) HRESULT Selected(VARIANT_BOOL) P AT260_DRG_E0 129 Developer Reference Guide HRESULT Visible(VARIANT_BOOL*) HRESULT Visible(VARIANT_BOOL) P 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 item’s 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 child’s 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("Prédictions") 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**) P HRESULT Remove() M HRESULT Position(long*) HRESULT Position(long) P HRESULT Object(IUnknown** o) P HRESULT Dispatch(IDispatch** d) P HRESULT ObjectKind(BSTR* retVal) P 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 parent’s 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); P HRESULT SetProperty([in] const BSTR bstrName, [in] const VARIANT varValue); M 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) P HRESULT ClassAttributes(ITabularData ** ppTable) P HRESULT DefaultAttributes(ITabularData ** ppTable) P 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) P HRESULT MeanSimulation(ISimulation** meanValues) P HRESULT Values) StdDevSimulation (ISimulation** stdDev- P 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 group’s 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 group’s 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) P HRESULT Statistics(ITabularData** ppTable) P HRESULT Cells(ITabularData ** pResults) P HRESULT Sites(ITabularData ** pResults) P HRESULTS Mobiles(ITabularData ** pResults) P 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 Simulation’s 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 Simulation’s 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: tion’s 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) P HRESULT ConvertCoordsTo(IDispCoordSystem *targetCS, VARIANT inPoints, VARIANT *outPoints) M HRESULT Datum(long *pVal) HRESULT Datum(long val) P HRESULT DatumName(BSTR *pVal) P HRESULT Description(BSTR *pVal) P HRESULT Ellipsoid(long* pVal) HRESULT Ellipsoid(long pVal) P HRESULT EllipsoidName(BSTR* pVal) P HRESULT Name(BSTR *pVal) HRESULT Name(BSTR pVal) P HRESULT Pick(OLE_HANDLE parentWindow, WORD types, VARIANT_BOOL *ret) M HRESULT ProjMethod(ProjectionMethod *pVal) P HRESULT ProjParameter(ProjParameterIndices index, double *pVal) P HRESULT SetDatum(long ellipsoidCode, VARIANT params) M HRESULT SetProjection(ProjectionMethod met, VARIANT projectionParameters) M HRESULT Unit(GeographicUnit *pVal) HRESULT Unit(GeographicUnit newVal) P 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 internalSystem; CComPtr 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 internalSystem; CComPtr projectionSystem; pDoc->get_CoordSystemInternal(&internalSystem); pDoc->get_CoordSystemProjection(&projectionSystem); CComPtr hiddenInternalSystem; CComPtr 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 won’t be detailed more than the following in this documentation. HRESULT Init([in] LPCSPARAMS params); // Init of a new CoordSystem HRESULT GetParams([out] LPCSPARAMS params); ordSystem’s 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() M HRESULT IsNetworkKey() M HRESULT GetFskKeyRef([in] BSTR* reference) 3.5.8.18.1 Property (P) Method (M) IApplicationKeyRef functions ULONG keyType, [out] M 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 Forsk’s 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 Forsk’s 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 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) P HRESULT ScenarioProvider ([out, retval] ITrafficScenarioProvider ** ppProvider) P 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) P HRESULT Create ([in] VARIANT selectedMapsNames,[in] double scale,[in] AtoTrafficScenarioLaw law,[in] VARIANT reserved,[out, retval] ITabularData **mobiles) P 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 X coordinate Long Projection coordinate system of the document Y 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); P HRESULT ClassAttributes([out, retval] ITabularData ** ppTable); P HRESULT DefaultAttributes([out, retval] ITabularData ** ppTable); P 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 you’ll 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 #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 Tutorial’s 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 Atoll’s 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 dll’s 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 0 Document has been successfully saved. atoSaveCanceled 1 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 0 Document is closed without being saved. AT260_DRG_E0 161 Developer Reference Guide atoSaveYes 1 Document is saved before being closed. atoSavePrompt 2 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 0 All changes in the document are cancelled before database is reloaded. atoSkipChanges 1 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 0 Archiving has succeeded. No conflicts. atoArchiveCanceled 1 Archiving has been cancelled (by the user or because conflicts occurred). Constant Value Description atoMaximized 0 Maximized (enlarged to maximum size). atoNormal 1 Normal (Default). atoMinimized 2 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 0 Uses the information icon for the message. atoError 1 Uses an error icon for the message. atoWarning 2 Uses a warning icon for the message. Constant Value Description atoEQ 0 (EQual) Specifies that the search is for the first value equal to searchVal. atoLT 1 (Strictly Lower Than) Specifies that the search is for the first value less than searchVal. atoLE 2 (Lower or Equal) Specifies that the search is for the first value less than or equal to searchVal. atoGE 3 (Greater or Equal) Specifies that the search is for the first value greater than or equal to searchVal. atoGT 4 (Strictly Greater Than) Specifies that the search is for the first value greater than searchVal. atoNE 5 (Not Equal) Specifies that the search is for the first value not equal to searchVal. Constant Value Description atoDbm 0 Transmission unit is dBm. atoWatt 1 Transmission Unit is Watt. atoKWatt 2 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 0 Reception Unit is dBm. atoDbMicroVolt 1 Reception Unit is DbµVolt. atoDbMicroVoltMeter 2 Reception Unit is DbµVolt /meter. See 3.5.8.3.12 ReceptionUnit property. 3.5.11.10 AtoDistanceUnit Constant Value Description atoM 0 Distance unit is meter. atoKm 1 Distance unit is kilometre. atoMiles 2 Distance unit is miles. See 3.5.8.3.13 DistanceUnit property. 3.5.11.11 AtoRadiatedPowerUnit Constant Value Description atoRadiatedPowerEIRP 0 Radiated power is EIRP. atoRadiatedPowerERP 1 Radiated power is ERP. See 3.5.8.6.3 RadiatedPowerUnit property. 3.5.11.12 AtoAntennaGainUnit Constant Value Description atoAntennaGainDbi 0 Antenna gain unit is dBi. atoAntennaGainDbd 1 Antenna gain unit is dBd. See 3.5.8.6.4 AntennaGainUnit property. 3.5.11.13 AtoHeightOffsetUnit Constant Value Description atoHeightOffsetM 0 Height offset unit is metre. atoHeightOffsetFeet 1 Height offset unit is feet. See 3.5.8.6.5 HeightOffsetUnit property. 3.5.11.14 AtoRootType Constant Value Description atoData 0 Requested tab is the data tab. atoGeo 1 Requested tab is the geo tab. atoModule 2 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 0 No filter. atoRowFilterModifiedOrNew 1 Filter to retain only modified or new rows. atoRowFilterDeleted 2 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 1 Row has been added. atoRowStatusModified 2 Row has been modified. atoRowStatusDeleted 4 Row has been deleted. atoRowStatusUnmodified 8 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 0 Length unit is meter. FgKilometer 1 Length unit is kilometre. FgFoot 2 Length unit is foot. FgLink 3 FgChain 4 FgYard 5 Length unit is Yard. FgNauticalMile 6 Length unit is Nautical Mile. FgMile 7 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 0 Value when nothing has been defined. fgNoProjection 1 This system has no projection method. fgLambertConfConic1SP 2 Lambert Conf Conic1 SP. fgLambertConfConic2SP 3 Lambert Conf Conic2 SP. fgMercator 4 Mercator. fgCassiniSoldner 5 Cassini Soldner. fgTransverseMercator 6 Transverse Mercator. fgTransvMercatorSouthOriented 7 Transverse Mercator South Oriented. fgObliqueStereographic 8 Oblique Stereographic. fgNewZealandMapGrid 9 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 0 Number of UTM zone. fgLongitudeOfOrigin 0 Longitude of the origin of the zone. fgLatitudeOfOrigin 1 Latitude of the origin of the zone. fgFalseEasting 2 False "easting". fgFalseNorthing 3 False "northing". fgScaleFactorAtOrigin 4 Scaling factor at the origin. fgLatitudeOf1stParallel 4 Latitude of the first parallel. fgAzimuthOfCentralLine 5 Azimuth of the central line. fgLatitudeOf2ndParallel 5 Latitude of the second parallel. fgAngleFromRecttifiedToSkewedGrid 6 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 X abscissa of the point. y 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); M HRESULT InvokeCommand(LPCMINVOKECOMMANDINFO lpici); M 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 Forsk’s Support website. The add-in’s source code is available upon request. It may be seen as a good starter’s 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 4 Basic AFP API 4.1 Introduction Since its inception and first implementation (2003), Forsk’s 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, Atoll’s 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 Atoll’s 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 0 HSN_TYPE 1 MAIO_TYPE 2 BSIC_TYPE 3 CODE_TYPE 4 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 0 Resource number can be assigned without grouping consideration, but still with restriction to BAND or SUB-BAND limitations. GROUP_ASSIGNENT4 1 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 0 No Frequency Hopping. BFH 1 BaseBand Frequency Hopping. SFH 2 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 0 Interference. RBER 1 Bit Error Rate. FER 2 Frame Error Rate. BLER 3 Block Error Rate. MOS 4 Mean option score (value 5 = EXCELLENT, 0 = BAD). USER_DEFINED 5 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 interface’s 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 it’s 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 i’th 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 i’th 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 *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 trg’s to assign cost+= IndividualTrgCost(coCellTrgs[t]); // other trg’s 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 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;grpContains(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 0 0.01 Probability of a user of a trx of trg being interfered by trgi, with a C/I<0db is 1% (0.01). 1 9 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). 2 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). x Y Y = probability that C/I (trgi->trgv) < x dB. … N 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(¤t); // 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(¤t); // 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(¤t); } … } … // 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: Don’t 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;trxGetResource(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 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 5 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 user’s 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 AFP’s 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 Forsk’s 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 file’s 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 it’s 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