Professional Documents
Culture Documents
Developer Reference Guide AT260 - DRG - E0 PDF
Developer Reference Guide AT260 - DRG - E0 PDF
Reference
Guide
2.6.0
AT260_DRG_E0
Developer Reference Guide
Contact Information
Forsk (USA Office) 200 South Wacker Drive L sales_us@forsk.com Sales and pricing information
Suite 3100 { support_us@forsk.com Technical support
Chicago, IL 60606 « +1 312 674 4846 General
USA +1 888 GoAtoll (+1 888 462 8655) Technical support
¬ +1 312 674 4847 Fax
Forsk (China Office) Suite 302, 3/F, West Tower, www.forsk.com.cn Web
Jiadu Commercial Building, L enquiries@forsk.com.cn Information and enquiries
No.66 Jianzhong Road, « +86 20 8553 8938 Telephone
Tianhe Hi-Tech Industrial Zone, ¬ +86 20 8553 8285 Fax (Guangzhou)
Guangzhou, 510665, +86 10 6513 4559 Fax (Beijing)
People’s Republic of China
The product or brand names mentioned in this document are trademarks or registered trademarks of their respective reg-
istering parties.
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.
Table of Contents
1 Introduction ..................................................................................... 19
1.1 Getting Started ....................................................................................................................................... 19
1.2 Prerequisites .......................................................................................................................................... 19
1.3 Supported Extensions ............................................................................................................................ 19
1.3.1 Propagation Models ......................................................................................................................... 19
1.3.2 Add-ins ............................................................................................................................................. 19
1.3.3 Macros.............................................................................................................................................. 20
1.3.4 Scripts .............................................................................................................................................. 20
1.3.5 Automatic Frequency Planning Models ............................................................................................ 20
1.3.6 Mixing Extensions ............................................................................................................................ 20
List of Figures
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:
• Read the Prerequisites to know about the development environment supported by this product.
• Read the paragraph Supported extensions to learn what you can do with the development toolkit.
• Follow the Tutorials1 step by step before starting your own development.
1.2 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.2 Add-ins
To facilitate extensions in Atoll by external developers, Forsk has introduced a technology greatly inspired from the Micro-
soft COM automation and add-in technology.
Add-ins allow advanced users to add specific tasks that can interact with the user during their Atoll session. Add-ins can
be built using any COM-compliant C++ development environment. For simplicity and clarity, this document provides exam-
ples using Microsoft Visual C++ only.
To learn more about Add-ins, please refer to chapter 3 "General API".
1. Currently, (Jan 2006) the wizard tutorials are only supported in Visual C++ .NET 2003 environment. 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.
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 sched-
uling tasks in batch mode. Scripts are written using VBScript.
To learn more about Scripts, please refer to chapter 3 "General 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.
4. Click OK and the Atoll ATL Project Wizard will open a dialog box offering several choices to configure the initial
ATL project.
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
Contains the implementation of DllMain, DllCanUnloadNow, DllGetClassObject,
UserMdl.cpp 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.
The resource file, which initially contains the version information and a string containing the
UserMdl.rc
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.
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.
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.
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. 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.
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.
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.
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:
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.
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.
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.
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:
equal =FALSE;
break;
}
else if (i==0)
{
aa=a;
bb=b;
cc=c;
}
}
HRESULT res=IPropertyPageImpl<CModel1Prop>::Activate(hWndParent, prc,
bModal);
if (equal)
{
char buffer[50];
gcvt(aa,5,buffer);
SetDlgItemText(IDC_A, buffer);
gcvt(bb,5,buffer);
SetDlgItemText(IDC_B, buffer);
gcvt(cc,5,buffer);
SetDlgItemText(IDC_C, buffer);
}
return res;
}
Similarly, enable the CModel1Prop class to set the parameters in your model when the Apply button is pressed. Change
the Apply function in CModel1Prop.h as follows:
STDMETHOD(Apply)(void)
{
ATLTRACE(_T("CModel1Prop::Apply\n"));
double a, b, c;
char buffer[50];
GetDlgItemText(IDC_A, buffer, sizeof(buffer));
a = atof(buffer);
GetDlgItemText(IDC_B, buffer, sizeof(buffer));
b = atof(buffer);
GetDlgItemText(IDC_C, buffer, sizeof(buffer));
c = atof(buffer);
for (UINT i = 0; i < m_nObjects; i++)
{
CComQIPtr<IModel1, &IID_IModel1> pModel1(m_ppUnk[i]);
pModel1->put_A(a);
pModel1->put_B(b);
pModel1->put_C(c);
}
m_bDirty = FALSE;
return S_OK;
}
A property page could have more than one client attached to it at a time. So, the Apply function loops back and calls put_X
on each client with the value retrieved from the three edit boxes. You are using the CComQIPtr class, which performs the
QueryInterface on each object to obtain the IModel1 interface from the IUnknown (stored in the m_ppUnk array).
CComPtr automatically handles the reference counting. So, you do not have to call Release on the interface. You also
must set the property page's dirty flag to indicate that the Apply button should be enabled. This occurs when the user
changes the value in one of the edit boxes. Add these lines to the message map in Model1Prop.h:
BEGIN_MSG_MAP(CModel1Prop)
CHAIN_MSG_MAP(IPropertyPageImpl<CModel1Prop>)
COMMAND_HANDLER(IDC_A, EN_CHANGE, OnParamChange)
COMMAND_HANDLER(IDC_B, EN_CHANGE, OnParamChange)
COMMAND_HANDLER(IDC_C, EN_CHANGE, OnParamChange)
END_MSG_MAP()
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
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 defi-
nition.
// 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.
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);
return S_OK;
}
Notes:
• 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.
Notes:
• No exception can be thrown between Atoll and the model. Each error must be notified by returning an
HRESULT error code.
• 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
POLAR_NONE No polarization or unknown polarization
POLAR_HORIZ Horizontal polarization
POLAR_VERT Vertical polarization
2.3.1.2 Pixel_Type
PIXEL_POINT Value is point-wise and is associated with the centre of a grid's mesh (corners of a 4-
point grid).
PIXEL_AREA The value is surface-area-wise and associated to a mesh of the grid.
2.3.1.3 Extraction_Mode
EXTRACT_DEFAULT All the geographic data present in Atoll document will be used.
Implemented
by
Format Mandatory Comments
ATL Object
Wizard
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 IGrid-
Data:
Implemented by
Mandator
Interface ATL Object Comments
y
Wizard
IGridData Yes Yes Management of a georeferenced matrix
To manage properties pages, the model must implement a class derived from IPropertyPage:
Implemented by
Mandator
Interface ATL Object Comments
y
Wizard
IPropertyPage No Yes Management of properties pages.
Notes:
• * 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).
IUnknown Description
QueryInterface Returns pointer to supported interfaces
AddRef Increments reference count
Release Decrements reference count
IPropagationModel Description
Calculates the attenuation of the signal from a given transmitter to a given receiver, on each
CalculateGrid
mesh of a grid defined by the model
Calculates the attenuation of the signal from a given transmitter to a given receiver, on each
CalculatePoints
given geographic point
HRESULT CalculateGrid(
[in] IRadioTransmitter* tx,
[in] IRadioReceiver* rx,
[in] IProgressCallback* cb,
[in] double resolution,
[in] double attmax,
[out] IGridData **pLoss)
Parameters
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 manda-
tory to use this parameter.
HRESULT CalculatePoints(
[in] IRadioTransmitter* tx,
[in] IRadioReceiver* rx,
[in] ULONG nPoints,
[in, size_is(nPoints)] GEOPOINTpts[],
[out, size_is(nPoints)] float loss[])
Parameters
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
_COM_SMARTPTR_TYPEDEF(IProgressCallback2, __uuidof(IProgressCallback2));
IProgressCallback2Ptr CModel::GetProgress()
{
IObjectWithSitePtr os = this;
IProgressCallback2Ptr sp;
os->GetSite(__uuidof(sp), reinterpret_cast<void**>(&sp));
return sp;
}
HRESULT CalculatePoints(IRadioTransmitter* tx, IRadioReceiver* rx, ULONG
nPoints, GEOPOINT pts[],float loss[])
{
…
IProgressCallback2Ptr progress=GetProgress();
progress->OnProgress(…
…
}
ImultiResPropagationMod
Description
el
CalculateGrids Calculates the multiple grids corresponding to the multiple resolutions
HRESULT CalculateGrids(
[in] IRadioTransmitter* tx,
[in] IRadioReceiver* rx,
[in] IProgressCallback* cb,
[in] IMultiResolution* res,
[out] IEnumGridData **pLoss)
Parameters
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.
Interface
public IOnProfilePropagationModel,
public IPropagationModel,
public ImultiResPropagationModel
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
}
}
T *begin() {return m_values;}
const T *begin() const {return m_values;}
T *end() {return m_values+m_size;}
const T *end() const {return m_values+m_size;}
T& operator[](int i) {
return m_values[i];}
const T& operator[](int i) const {
return m_values[i];}
};
// Utility typedef
typedef CComEnum<IEnumGridData, &__uuidof(IGridData), IGridData*,
_CopyInterface<IGridData> > CPropagResultEnumerator;
IGridData* result=NULL;
HRESULT res=CalculateGrid(tx,rx,cb,sresol[iRes],0,&result);
if (res==S_OK)
allResults[iRes]=result;
else
{
delete result;
*pLoss = NULL;
return E_FAIL;
}
}
CComObject<CPropagResultEnumerator> *pRet;
CComObject<CPropagResultEnumerator>::CreateInstance(&pRet);
pRet->Init(allResults.begin(), allResults.end(), NULL, AtlFlagCopy);
*pLoss = pRet;
(*pLoss)->AddRef();
}
catch(_com_error& err)
{
HRESULT res=E_ABORT;
if (err.Error()!=res)
res=AtlReportError(GetObjectCLSID(),LPOLESTR(err.Descrip-
tion()),__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(IPropaga-
tionModel));
…
…
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;
…
IUnknown Description
QueryInterface Returns pointer to supported interfaces
AddRef Increments reference count
Release Decrements reference count
IOnProfilePropagationModel Description
Calculates the signal attenuation and draws the profile between a given
CalculateProfile
transmitter and a receiver at a given position.
HRESULT CalculateProfile(
Parameters
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
IOnProfilePropagationMode
Description
l2
ShowDetails Gives details about the calculation of a specific profile.
HRESULT ShowDetails(
[in] IRadioTransmitter *tx,
[in] IRadioReceiver *rx,
[in] GEOPOINT *pt)
Parameters
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).
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:
IRadioTransmitter Manages transmitter properties.
IRadioReceiver Manages receiver properties.
IProgressCallback Manages calculation progress.
IUnknown Description
QueryInterface Returns pointer to supported interfaces
AddRef Increments reference count
Release Decrements reference count
IRasterGeoData 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.
Parameters
Return Values
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
HRESULT ExtractProfile(
[in] GEOPOINT *from,
[in] GEOPOINT *to,
[in] DWORD flags,
[in] ULONG nPts,
[in] double *dist,
[out] VARIANT *profile)
Parameters
Return Values
HRESULT GetValueType(
[in] GEOPOINT *pt,
[in] DWORD flags,
[out] VARIANT *value)
Parameters
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
HRESULT PrepareFastAccessData(
[in] GEORECT *bounds,
[out] IRasterGeoData **ppData)
Parameters
bounds: Geographic zone for which the data is pre-loaded. If this argument is NULL, all the
geographic data will be loaded.
ppData: Geographic data in memory covering the bounds zone.
Return Values
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.
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.
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: Object enabling iteration on the list of surface-area-wise geographic data intersecting
bounds.
Return Values
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
Parameters
Return Values
HRESULT GetItemProperties(
[in] ULONG index,
[out] BSTR *name,
[out] DWORD *code,
[out] float *height,
[out] DWORD *color);
Parameters
Return Values
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
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
HRESULT Next(
[in] ULONG celt,
[out] IGridData **rgelt,
[out] ULONG * pceltFetched )
Parameters
Return Values
Parameters
Return Values
HRESULT Reset()
Return Values
S_OK.
Parameters
ppenum: Pointer's address of the new enumerator. If this method fails, the final value of this
argument is undefined.
Return Values
This method supports the standard Return Values E_INVALIDARG, E_OUTOFMEMORY and E_UNEXPECTED.
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
HRESULT GetDimension(
[out] GEOPOINT *pt,
[out] ULONG* nx, [out] ULONG* ny,
[out] double *resX, [out] double *resY)
Parameters
Return Values
If any one among pt, nx, ny, resX and resY is NULL, this method returns E_POINTER,
Else it returns S_OK.
HRESULT GetPixelType(
[out] PIXEL_TYPE *type)
Parameters
type: Type of the values from the matrix. Can take two different values (see 2.3.1.2
Pixel_Type):
PIXEL_AREA
PIXEL_POINT
Return Values
HRESULT ExtractSubGrid(
[in] ULONG i0,
[in] ULONG j0,
[in] ULONG nX,
[in] ULONG nY,
[out] VARIANT *grid)
Parameters
Return Values
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
Parameters
Return Values
Parameters
Return Values
Parameters
azimuth: Azimuth value of the antenna. Angle in degrees measured from the North in the clock-
wise direction.
Return Values
Parameters
tilt: Value of the antenna's tilt angle. Angle in degrees measured from the horizontal plane
increasing downwards.
Return Values
Parameters
Return Values
Parameters
Return Values
Parameters
Return Values
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
Parameters
Return Values
IRadioTransmitter
Description
2
GetTransmitterId Returns the transmitter's record id
GetEirp Returns the EIRP (in dBm) of the transmitter
GetFieldValue Returns predefined field values of the transmitter
Parameter
Return Values
If id is NULL, E_POINTER,
Else S_OK.
Parameters
Return Values
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
Predefined Fields
Private usage of the dev. Please don’t use this value because the result
“CALC_RADIUS”
is undefined.
Private usage of the dev. Please don’t use this value because the result
“TYPE”
is undefined.
Private usage of the dev. Please don’t use this value because the result
“CODE_SERVICE”
is undefined.
TypeDefs
Enumerations
Parameters
Return Values
Examples
IUnknown IUnknownDescription
QueryInterface Returns pointer to supported interfaces
AddRef Increments reference count
Release Decrements reference count
IRadioTransmitter Description
GetHeight Returns the receiver's height
Parameters
Return Values
IProgressCallback Description
OnProgress Updates the calculation progress
HRESULT OnProgress(
[in] DWORD progressCurrent,
[in] DWORD progressMaximum)
Parameters
Return Values
IProgressCallback
Description
2
SetStatusText Displays a message in the events observer.
HRESULT SetStatusText(
[in] LPCWSTR szStatusText)
Parameters
Return Values
S_OK.
Parameters
} PROGRESS_EVENT_TYPE;
Return Values
S_OK.
E_FAIL, if an error occurs while trying to display a message.
IMultiResolution Description
GetCount Number of supported resolutions
GetResolution Gives the characteristics of a given resolution
Parameters
Return Values
Remarks
HRESULT GetResolution(
[in] long index,
[out] double *radius,
[out] double *resolution)
Parameters
Return Values
IMeasurements Description
GetName Gets the name of the measurements item.
GetTransmitter Gets the transmitter to which the measurements item is attached.
Parameters
Return Values
S_OK.
Parameters
Return Values
S_OK.
Parameters
Return Values
S_OK.
Parameters
Return Values
S_OK.
HRESULT GetLocations(
[in] ULONG start,
[in] ULONG count,
[out, size_is(count)] GEOPOINT *locations,
[out] ULONG *pceltFetched)
Parameters
Return Values
S_OK.
HRESULT GetLocations(
[in] ULONG start,
[in] ULONG count,
[out, size_is(count)] double *measurements,
[out] ULONG *pceltFetched)
Parameters
Return Values
S_OK.
IEnumMeasurement
Description
s
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
HRESULT Next(
[in] ULONG celt,
[out] IMeasurements **rgelt,
[out] ULONG * pceltFetched )
Parameters
Return Values
Parameters
Return Values
HRESULT Reset()
Return Values
S_OK.
Parameters
ppenum: Pointer's address of the new enumerator. If this method fails, the final value of this
argument is undefined.
Return Values
IMeasurementsCatalo
Description
g
EnumMeasurements 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: Enumerator on the objects implementing IMeasurements interface.
Return Values
Code Example
Remarks
Parameters
Return Values
HRESULT Reset()
Return Values
S_OK.
Parameters
ppenum: Pointer's address of the new enumerator. If this method fails, the final value of this
argument is undefined.
Return Values
This method supports the standard Return Values E_INVALIDARG, E_OUTOFMEMORY and E_UNEXPECTED.
IAntenna Description
GetFieldValue Gets antenna properties.
GetSectionCount Gets the count of antenna diagram sections.
GetSection Gets an antenna diagram section interface pointer.
Parameters
Return Values
Example
Antenna diagrams are made of several sections for different orientation and tilt/azimuth values.
Parameters
pCount: A pointer to the location where this method writes the section count of the antenna
diagram.
Return Values
Example
Parameters
index: Index of the antenna diagram section. Valid indexes are in the interval [0, (section
count)[.
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
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))
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];
hr = pSection->GetPattern(ulSize, pPattern);
if (FAILED(hr))
throw hr;
for (ULONG k = 0; k < ulSize; ++k)
{
CString l;
l.Format(_T("%d : %lf %lf\r\n"), k, pPattern[k].angle,
pPattern[k].loss);
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;
}
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.
2.3.3.14.2 TypeDefs
Gives the loss in dB for a given angle:
2.3.3.14.3 Enumerations
Orientation of a antenna diagram section:
Parameters
pOrientation: A pointer to the location where this method writes the section orientation.
pAngle: A pointer to the location where this method writes the tilt for an horizontal section or
the azimuth for a vertical section.
Return Values
Example
Parameters
pCount: A pointer to the location where this method writes the section size.
Return Values
Example
Parameters
Example
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
2.3.3.15.1 Example
Example of IEnumAntennas is available in section 2.3.3.13.4.
HRESULT Next ([in] ULONG celt, [out] IAntenna ** ppElements, [out] ULONG *
pceltFetched)
Parameters
Return Values
Example
Parameters
Return Values
HRESULT Reset ()
Return Values
Parameters
Return Values
From Atoll version 2.2.2, the access permission is also allowed for the following fields:
[RemoteCalculation]
NumberOfThreads=1
3 General API
The general API enables the implementation of add-ins, macros, and scripts.
5. Click OK and the Atoll ATL Project Wizard will open a dialog box offering several choices to configure the initial
ATL project.
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
Contains the implementation of DllMain, DllCanUnloadNow, DllGetClassObject,
UserAddIn.cpp 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.
The resource file, which initially contains the version information and a string containing the
UserAddIn.rc
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.
A set of property pages is displayed that enable you to configure the add-in you are inserting into your project.
• 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.
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.
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.
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.
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 Calcu-
late 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).
Option Explicit
Dim var
Dim myapp
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=my-
Name;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.
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:
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).
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.
Myapp.Visible = True
Option Explicit
Dim var
Dim myapp
Dim doc
On Error Resume Next
Sub CatchError
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=my-
Name;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.
mydoc = ActiveDocument
The global object’s name is “Atoll” and is optional. So, the above line is equivalent to:
mydoc = Atoll.ActiveDocument
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 manu-
ally.", 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.
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.
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
Differences are:
• The use of interface pointers,
• The HRESULT returned value
• The prefix 'get_' to read the property and 'put_' to set it.
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.
theObject.RunTheMethod()
Or
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:
For clarity, error handling is omitted from code samples in this document.
Because Atoll registers itself in the Running Objects Table when an Atoll session is running, you can use:
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.
LogMessage Displays a message in the Atoll events’ viewer window (Error, Warning or Info).
Dim allDocs
Set allDocs = app.Documents
IDocumentsPtr pDocs;
HRESULT hr = m_spApplication->get_Documents(&pDocs);
if (FAILED(hr))
return hr;
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)
You can also add a new document to the Documents collection or open a new document from database (see 3.5.3 Docu-
ments 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));
Some of the following methods take required or optional arguments, which are deliberately not listed here. Refer to the
“Detailed description” for more information.
• 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:
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.
Dim doc
Dim coordSys
Set doc = app.ActiveDocument
Set coordSys = doc.CoordSystemInternal
And in C++:
IDocumentPtr pDoc;
HRESULT hr = m_spApplication->get_ActiveDocument (&pDoc);
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);
Or
variant_t vis = false;
app->put_Visible(vis);
CComPtr<IApplication> m_spApplication;
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.
Property (P)
Object Function
Method (M)
HRESULT Active(VARIANT_BOOL*)
Application P
HRESULT Active(VARIANT_BOOL)
HRESULT ActiveDocument(IDocument**) P
HRESULT AddCommand(BSTR, BSTR, VARIANT_BOOL,
M
long, VARIANT_BOOL*)
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,
M
long)
HRESULT StatusBar(BSTR) P
HRESULT Version(BSTR*) P
HRESULT Visible(VARIANT_BOOL*)
P
HRESULT Visible(VARIANT_BOOL)
HRESULT WindowStatus(AtoWindowStatus*)
P
HRESULT WindowStatus(AtoWindowStatus)
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.
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.
Parameters
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.
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)
{
//...
}
Parameters
Return Values
S_OK.
E_POINTER, if pVal is NULL.
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”).
Parameters
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”).
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)
{
//...
}
Parameters
Return Values
S_OK.
E_POINTER, if pVal is NULL.
Example
VBScript:
Dim app
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) ;
//...
}
Parameters
Return Values
S_OK.
Example
VBScript:
Dim app
Set app = GetObject(, “Atoll.Application”)
app.StatusBar = “This is my message”
C++:
Parameters
Return Values
S_OK.
E_POINTER, if pVal is NULL.
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.
Parameters
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)”).
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 AtoSav-
eStatus.
Return Values
S_OK.
E_POINTER, if status is NULL.
Parameters
Return Values
S_OK.
Parameters
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.
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: A String that represents the method exposed by the add-in to implement the
command.
toolbar: A boolean that tells Atoll if this command is assigned to a button in the toolbar. If tool-
bar 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 add-
in 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.
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
}
Parameters
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;
long nDocs = 0;
hr = pDocs->get_Count(&nDocs);
if (FAILED(hr)) return hr;
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.
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.
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.
4. Depends on checkbox Hide File Extensions for known file types in the tab “Tools Folder Options Display” of
Windows Explorer.
Parameters
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;
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;
Parameters
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;Us-
er ID = USERID;Data Source=C:\Temp\MyProject.mdb","")
Dim doc
Set doc = app.Documents.OpenFromDatabase("Provider=Microsoft.Jet.OLEDB.4.0;Us-
er ID = USERID;Data Source=C:\Temp\MyProject.mdb", ";sitelist0")
Notes:
• Do not forget the semi-colon (;) before sitelist0.
Dim doc
Set doc = app.Documents.OpenFromDatabase("Provider=Microsoft.Jet.OLEDB.4.0;Us-
er ID = USERID;Data Source=C:\Temp\MyProject.mdb", "DontKeepConnection
;;sitelist0")
Notes:
• Do not forget the two consecutive semi-colons (;;) before sitelist0.
C++:
IDocumentsPtr pDocs;
HRESULT hr = m_spApplication->get_Documents(&pDocs);
IDocumentPtr pDoc;
pDocs-> OpenFromDatabase (_variant_t("Provider=Microsoft.Jet.OLEDB.4.0;User ID
= USERID;Data Source=C:\\Temp\\MyProject.mdb"), _bstr_t(";<ALL>"), &pDoc);
IDocumentsPtr pDocs;
hr = m_spApplication->get_Documents(&pDocs);
CComPtr<IDocument> pDoc;
_variant_t connexion("Provider=MSDAORA.1;User ID = USERID;Data
Source=SOURCE;Password=P");
pDocs-> OpenFromDatabase (connexion, _bstr_t("DontKeepConnec-
tion;USERID;sitelist0; sitelist1"), &pDoc);
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.
HRESULT SaveAll();
Parameters
None.
Return Values
S_OK.
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;
bounds.west = 985800; bounds.east = 987300;
bounds.south = 1879100; bounds.north = 1880700;
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:
Interface Isignals, which was added in Atoll 2.2.2, only supports GetSortedSignals function described further in this docu-
ment.
Property (P)
Object Function
Method (M)
Document HRESULT Application(IApplication**) P
HRESULT Archive(AtoArchiveStatus*) M
HRESULT CenterMapOn(double*, double*) M
HRESULT Close(AtoSaveChanges, AtoSaveStatus*) M
HRESULT CoordSystemDisplay(IDispCoordSystem**)
P
HRESULT CoordSystemDisplay(IDispCoordSystem*)
HRESULT CoordSystemInternal(IDispCoordSystem**) P
HRESULT CoordSystemProjection(IDispCoordSystem**)
P
HRESULT CoordSystemProjection(IDispCoordSystem*)
HRESULT DistanceUnit(AtoDistanceUnit*)
P
HRESULT DistanceUnit(AtoDistanceUnit)
HRESULT FilePrint() M
HRESULT FullName(BSTR*) P
HRESULT GetRecords(BSTR, VARIANT_BOOL, ITabularData**) M
HRESULT GetRootFolder(AtoRootType,IChildFolder**) M
HRESULT Import(BSTR) M
HRESULT Name(BSTR*) P
HRESULT Parent(IApplication**) P
HRESULT Path(BSTR*) P
HRESULT ReadOnly(VARIANT_BOOL*) P
HRESULT ReceptionUnit(AtoReceptionUnit*)
P
HRESULT ReceptionUnit(AtoReceptionUnit)
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 *)
P
HRESULT TransmissionUnit(AtoTransmissionUnit)
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.
Parameters
pVal: Address of pointer variable that receives the documents interface pointer. See 3.5.8.2
IDocuments.
Return Values
S_OK.
E_POINTER, if pVal is NULL.
Parameters
pVal: Address of string that receives the document’s full path name.
Return Values
S_OK.
E_POINTER, if pVal is NULL.
Parameters
Return Values
S_OK.
E_POINTER, if pVal is NULL.
Parameters
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.
Parameters
Return Values
S_OK.
E_POINTER, if pVal is NULL.
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.
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.
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.
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.
Parameters
pVal: Address of an integer variable that receives the unit (see 3.5.11.8 AtoTransmissionU-
nit).
newVal: Integer containing the new unit.
Return Values
S_OK.
E_POINTER, if pVal is NULL.
Parameters
pVal: Address of an integer variable that receives the unit (see 3.5.11.9 AtoReceptionUnit).
Return Values
S_OK.
E_POINTER, if pVal is NULL.
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.
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.
HRESULT FilePrint();
Parameters
None.
Return Values
S_OK.
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.
Return Values
S_OK or E_FAIL.
Examples
IDocumentPtr pDoc;
hr = m_spApplication->get_ActiveDocument(&pDoc);
pDoc->Save(_bstr_t(L"C:\\Temp\\MyProject.atl"));
return S_OK;
IDocumentPtr pDoc;
hr = m_spApplication->get_ActiveDocument(&pDoc);
pDoc->Save(_bstr_t((L"C:\Temp\MyProject.mdb"));
return S_OK;
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;
Parameters
priority: A Long value that tells Atoll if previous changes in the project file must be kept or not
(see 3.5.11.3 AtoRefreshPriority).
Return Values
S_OK or E_FAIL.
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.
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.
Return Values
S_OK or E_FAIL.
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.
Parameters
fileName: String containing the full path name of the file to load.
Return Values
S_OK or E_FAIL.
Remarks
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.
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-to-
date: 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;
HRESULT Redraw();
Parameters
None.
Return Values
S_OK.
Remarks
It has the same effect as the icon “Refresh” (F5) in Atoll GUI.
Parameters
ptx, pty: Double values that hold the coordinates of the point. The coordinate system must be
the same as in the document.
Return Values
S_OK.
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.
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;
(This code is extracted from the Best Signals Export add-in available upon request from support@forsk.com).
HRESULT GetSortedSignals(
[in] GEORECT *zone,
[in] double resolution,
[in] double minSignalLevel,
[in] double maxSignalDifference,
[in] ULONG depth,
[in] IUnknown pServers, // Txs
[out] IMultiGridData **pSignals,
[out] IMultiGridData **pServerNumbers
);
Parameters
pServers: Pointer to the transmitters that must be taken into account in the calculation.
pSignals: Pointer to MultiGridData containing the n Best Signal Matrices. Contained values are
field levels.
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.
(This code is extracted from the Best Signals Export add-in available upon request from support@forsk.com).
HRESULT GetSortedServers(
[in] GEORECT *zone,
[in] double resolution,
[in] double minSignalLevel,
[in] double maxSignalDifference,
[in] ULONG depth,
[in] IUnknown pServers, // Txs
[in] ULONG ulSortOption, // OR of BEST_SERVER_OPTIONs
[out] IMultiGridData **pSignals,
[out] IMultiGridData **pServerNumbers
);
Parameters
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 GetSortedSig-
nals 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: Pointer to MultiGridData containing the n Best Signal Matrices. Contained values are
field levels.
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.
Property (P)
Object Function
Method (M)
Document HRESULT RunPathloss (VARIANT_BOOL,VARIANT_BOOL) M
HRESULT GetService (BSTR, IDispatch**) P
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 avail-
able 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 calcu-
lation” available in the Calculations sub-menu of the Transmitters folder.
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: Address of an IDispatch pointer receiving the object that implements the requested
service.
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).
Property (P)
Object Function
Method (M)
Document HRESULT ExportConfig (BSTR content, BSTR file) M
Parameters
Return Values
Property (P)
Object Function
Method (M)
HRESULT GetCommandDefaults([in] const BSTR bstrCommand-
Document P
Name, [out, retval] IPropertyContainer **ppParameters);
HRESULT InvokeCommand([in] const BSTR bstrCommandName,
[in, unique, defaultvalue(NULL)] IPropertyContainer
P
*pParameters, [out, retval] IPropertyContainer **ppRe-
sults);
HRESULT RadiatedPowerUnit([out, retval] enum AtoRadiat-
edPowerUnit *pVal);
P
HRESULT RadiatedPowerUnit([in] enum AtoRadiatedPowerU-
nit aNewVal);
HRESULT AntennaGainUnit([out, retval] enum AtoAntenna-
GainUnit *pVal);
P
HRESULT AntennaGainUnit([in] enum AtoAntennaGainUnit
aNwVal);
Parameters
Return Values
Parameters
Return Values
Parameters
pVal: Address of an integer variable that receives the unit (see 3.5.11.11 AtoRadiated-
PowerUnit).
aNewVal: Integer containing the unit.
Return Values
S_OK.
E_POINTER, if pVal is NULL.
Parameters
pVal: Address of an integer variable that receives the unit (see 3.5.11.12 AtoAntenna-
GainUnit).
aNewVal: Integer containing the unit.
Return Values
S_OK.
E_POINTER, if pVal is NULL.
Parameters
pVal: Address of an integer variable that receives the unit (see 3.5.11.13 AtoAntenna-
GainUnit).
aNewVal: Integer containing the unit.
Return Values
S_OK.
E_POINTER, if pVal is NULL.
Property (P)
Object Function
Method (M)
HRESULT Build (BSTR, BSTR, long, long, long, long,
ResultFileProvider M
long, long*, long*)
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.
Remarks
The parameter name of GetService function can either be SIGNAL or the CLSID of this class: L"{B02A59E4-0F56-4FD1-
A71A-454576912A20}".
Currently only ASCII .txt file format is supported. The values surrounding the computed ones are set to –FLT_MAX.
Property (P)
Object Function
Method (M)
TabularData HRESULT AddNew() M
HRESULT ColumnCount(long*) P
HRESULT Delete(long) M
HRESULT Edit(long) M
HRESULT Find(long, VARIANT, AtoCompareOp, VARIANT,
M
long*)
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
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.
Parameters
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
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.
Parameters
Return Values
S_OK, if 0 < iRow GetRowCount() and no record is currently being edited or added,
Else E_INVALIDARG.
Notes:
• Don’t forget to call this method before a call to SetValue and to call Update to end the changes in the
record.
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:
• 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.
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
Remarks
This method must be called once after each Edit and AddNew. Editing one record after another without updating the previ-
ous one will throw an error. Edit/Update cannot be mixed up for different record, neither can be AddNew/Update.
Parameters
iRow: Long containing the number of the row of the record which must be deleted.
Return Values
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.
Parameters
Return Values
Remarks
A valid iRow number is any integer, such that 0 iRow RowCount(). A valid iCol is either an integer such that 0 iCol Colum-
nCount() 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:
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);
}
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”)
transmitters.Edit(i)
transmitters.SetValue(“TXLOSSES”, txLosses + 1)
transmitters.Update()
Next i
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 = (pDoc->GetRecords(CComBSTR(_T("Transmitters")),
VARIANT_TRUE, &pRecords))))
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();
}
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
Parameters
Return Values
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.
Parameters
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.
Parameters
iRowStart: Position of the first row at which the search operation begins.
vCol: Index or Name of the column concerned with the search.
op: An integer that specifies the kind of search (equal, greater, less than, equal to, etc).
See 3.5.11.7 AtoCompareOp.
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
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
Remarks
A valid iRow number is an integer such that 0 iRow RowCount(). A valid iCol is either an integer such that 0 iCol Colum-
nCount() or a string containing the name of an existing column. The column names are not case sensitive.
Notes:
• 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.
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_);
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
{
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 = points2_.vt;
value.parray = points2_.parray;
points2_.vt = VT_EMPTY;
zones->SetValue(POINTS, value);
long ri_;
zones->Update(&ri_);
}
return TRUE;
}
ITabularDataPtr pTransmitters;
…
…
_variant_t v;
IRadioTransmitter3Ptr pRadioTransmitter;
pTransmitters->GetValue(1, _variant_t(L”_RADIO_TRANSMITTER”), &v);
IRadioTransmitter3Ptr pRadioTransmitter;
pRadioTransmitter = V_UNKNOWN(&v);
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
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)
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
Property (P)
Object Function
Method (M)
TabularData2 HRESULT CancelUpdate() M
HRESULT ColumnNumber([in] VARIANT vColName, [out,
P
retval] long *pCol)
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)
P
HRESULT Filter([out, retval] VARIANT *pvCriteria)
HRESULT Sort([in] VARIANT vCriteria)
P
HRESULT Sort([out, retval] VARIANT *pvCriteria)
HRESULT CancelUpdate();
Parameters
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:
Parameters
Return Values
S_OK.
VARIANT_FALSE, if the Edit operation on this table is undefined.
Parameters
Return Values
S_OK.
VARIANT_FALSE, if the AddNew operation on this table is undefined.
Parameters
Return Values
S_OK.
VARIANT_FALSE, if Filter and Sort operations on this table are undefined.
Parameters
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.
Parameters
Return Values
S_OK.
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
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
Parameters
Return Values
S_OK.
HRESULT GetOriginalValue([in] long iRow, [in] VARIANT iCol, [out, retval] VAR-
IANT *pVal);
Parameters
Return Values
S_OK.
Remarks
If the row is unmodified, the original value is the same as the value itself.
Parameters
Return Values
S_OK.
Parameters
Return Values
Remarks
Parameters
Return Values
Remarks
HRESULT Visible(VARIANT_BOOL*)
P
HRESULT Visible(VARIANT_BOOL)
The available properties of a ChildFolder object depend on the exact type of ChildFolder object returned by the ObjectKind
property.
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
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.
Parameters
Return Values
S_OK.
E_POINTER, if pVal is NULL.
Example
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”
End if
Next
Parameters
Return Values
S_OK.
E_POINTER, if pVal is NULL.
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.
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 imple-
mentation of “For Each ... Next”.
Example
VBScript:
C++:
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
}
Parameters
pVal: Address of the pointer variable that receives VARIANT_TRUE, if the child is visible,
and VARIANT_FALSE otherwise.
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
Parameters
pVal: Address of the pointer variable that receives VARIANT_TRUE, if the child is selected,
or VARIANT_FALSE otherwise.
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:
Parameter
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:
HRESULT CentreOnMap();
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.
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.
Parameters
Return Values
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.
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.
Return Values
S_OK.
E_POINTER, if pos is NULL.
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.
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.
Parameters
Return Values
S_OK.
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
≥
Access to “tabular”
2.4.0 SID_CLUTTER {7CB51DE8-A961-11D2-8688-0060086457D1} clutter properties.
See IClutter interface
Access to Simulations
2.4.0 SID_SIMULATIONS {CDDF1E1D-1963-4D80-A057-D23A19570984}
folder
Access to “Groups of
2.4.0 SID_SIMULATIONSGROUP {AF5E2B98-1D54-48FA-89C5-8BFA2936ABF2}
simulations“ subfolder
Access to
“Simulation” items.
2.4.0 SID_SIMULATION {095C5D90-96F1-4BA8-85BB-B2F990AC2DD9}
See ISimulation
interface
2.5.1 SID_SITES {90443F68-5B3B-4AFD-B7BB-B057095EBAAD} Access to Sites folder
Access to Antennas
2.5.1 SID_ANTENNAS {5FBEB2AE-3BBB-4FBA-94D8-5D8EA5A32069}
folder
Access to
2.5.1 SID_TRANSMITTERS {F7E891E8-F7F5-4870-BF63-AF559AD50FD3}
Transmitters folder
Access to Predictions
2.5.1 SID_PREDICTIONS {DA676EF0-E300-4AFF-BBFA-EC55D3798E4F}
folder
Access to UMTS
2.5.1 SID_UMTS_PARAMETERS {D4F57EE3-7785-4348-9BA6-28998AA6BD80}
Parameters folder
Access to CW
2.5.1 SID_CW_MEASUREMENTS {41413C4A-C9DE-43DD-A917-612A0AF198FC}
Measurements folder
Access to CW
2.5.1 SID_MEASURE_TX {2C102EE5-BFF4-4A5A-8130-02BD0E2F70D7} Measurements
Transmitter
Access to CW
2.5.1 SID_MEASURE_ITEM {36858A48-7A85-482E-9DA0-B9E935ADE84C}
Measurements
Access to Test Mobile
2.5.1 SID_TESTMOBILEDATA {21C11380-D8CF-4902-B622-763522AD9FC4}
Data folder
Access to Test Mobile
2.5.1 SID_NUM_MEASURE_ITEM {916801F9-0539-448C-8C0C-491FAC6399ED}
Data
Access to Parameters
2.5.1 SID_PARAMETERS_FOLDER {43B8845-5226-454F-908F-59A500DB4FD1}
folder
Access to Hexagonal
2.5.1 SID_HEXAGON_SCHEMA {B167D45E-A0BC-4DC6-B9D7-6F7B131CADF1}
Design folder
Access to Traffic
2.6.0 SID_TRAFFICFOLDER {B3B25A07-A994-4e8d-BBD1-51556D6C4245}
folder
Parameters
Return Values
Remarks
Parameters
Return Values
Remarks
Parameters
pSource: Pointer to the folder corresponding to the functionnality (Clutter Classes folder)
Return Values
Parameters
Return Values
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.
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
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
Parameters
pSource: Pointer to the folder corresponding to the functionnality (here Simulation Groups
folder).
Return Values
Parameters
Return Values
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
Parameters
stdDevValues: Pointer to the virtual standard deviation simulation created to display standard devia-
tion values for the different kind of results provided in the end of execution of simulations of the group.
Return Values
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.
Property (P)
Object Function
Method (M)
Simulation 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
Parameters
pSource: Pointer to the folder corresponding to the functionnality (here Simulation folders).
Return Values
Parameters
Return Values
Parameters
pResults: Pointer to the table of results corresponding to the Cells tab of the Simulation’s Prop-
erty Page.
Return Values
Parameters
pResults: Pointer to the table of results corresponding to the Cells tab of the Simulation’s Prop-
erty Page.
Return Values
Parameters
pResults: Pointer to the table of results corresponding to the Cells tab of the Simula-
tion’s Property Page.
Return Values
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.
Property (P)
Object IDispCoordSystem functions
Method (M)
HRESULT Code(long *pVal)
CoordSystem P
HRESULT Code(long val)
HRESULT ConvertCoordsTo(IDispCoordSystem *targetCS,
M
VARIANT inPoints, VARIANT *outPoints)
HRESULT Datum(long *pVal)
P
HRESULT Datum(long val)
HRESULT DatumName(BSTR *pVal) P
HRESULT Description(BSTR *pVal) P
HRESULT Ellipsoid(long* pVal)
P
HRESULT Ellipsoid(long pVal)
HRESULT EllipsoidName(BSTR* pVal) P
HRESULT Name(BSTR *pVal)
P
HRESULT Name(BSTR pVal)
HRESULT Pick(OLE_HANDLE parentWindow, WORD types,
M
VARIANT_BOOL *ret)
HRESULT ProjMethod(ProjectionMethod *pVal) P
HRESULT ProjParameter(ProjParameterIndices index, double
P
*pVal)
HRESULT SetDatum(long ellipsoidCode, VARIANT params) M
HRESULT SetProjection(ProjectionMethod met, VARIANT
M
projectionParameters)
HRESULT Unit(GeographicUnit *pVal)
P
HRESULT Unit(GeographicUnit newVal)
Parameters
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:
• Classical system codes have values less than 32767. System codes greater or equal to 32768 correspond
to user defined systems.
Parameters
targetCS: Pointer of the coordinates system to which input coordinates must be converted.
InPoints: Coordinates of the input point to convert expressed in the current system. Array of 2
VT_R8: x and y.
OutPoints: Coordinates of the output converted point expressed in targetCS. Array of 2 VT_R8:
x and y.
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 param-
eters 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;
VBScript:
There is another possibility to convert point coordinates in a more friendly way, using a hidden interface named ICoordSys-
tem:
To use this function available on ICoordSystem interface, you must get this interface from the object implementing the
IDispCoordSystem interface, using QueryInterface method.
CComPtr<IDispCoordSystem> internalSystem;
CComPtr<IDispCoordSystem> projectionSystem;
pDoc->get_CoordSystemInternal(&internalSystem);
pDoc->get_CoordSystemProjection(&projectionSystem);
CComPtr<ICoordSystem> hiddenInternalSystem;
CComPtr<ICoordSystem> hiddenProjectionSystem;
internalSystem->QueryInterface(__uuidof(ICoordSystem),(void**)&hiddenInter-
nalSystem);
projectionSystem->QueryInterface(__uuidof(ICoordSystem),(void**)&hiddenPro-
jectionSystem);
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.
Parameters
Return Values
S_OK.
E_POINTER, if pVAl is NULL.
E_INVALIDARG, if val does not correspond to a datum code recognized by Atoll.
Parameters
Return Values
S_OK.
E_POINTER, if pVAl is NULL.
Parameters
Return Values
S_OK.
E_POINTER, if pVAl is NULL.
Parameters
Return Values
S_OK.
E_POINTER, if pVal is NULL.
E_INVALIDARG, if val does not correspond to an ellipsoid code recognized by Atoll.
Parameters
Return Values
S_OK.
E_POINTER, if pVal is NULL.
Parameters
Return Values
S_OK.
E_POINTER, if pVAl is NULL.
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: Pointer to a VARIANT_BOOL, set to VARIANT_TRUE if the user quits the dialog with
OK, otherwise VARIANT_FALSE.
Return Values
S_OK.
E_POINTER, if ret is NULL.
CoordSysTypes
enum CoordSysType
{ fgUndefinedCoordSys = 1,
fgGeographic2D = 2,
fgProjected2D = 4
} CoordSysType;
Parameters
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;
Parameters
Return Values
S_OK.
ProjParameterIndices
enum ProjParameterIndices
{
fgUTMZoneNumber = 0,
fgLongitudeOfOrigin = 0,
fgLatitudeOfOrigin = 1,
fgFalseEasting = 2,
fgFalseNorthing = 3,
fgScaleFactorAtOrigin = 4,
fgLatitudeOf1stParallel = 4,
fgAzimuthOfCentralLine = 5,
fgLatitudeOf2ndParallel = 5,
fgAngleFromRectfifiedToSkewedGrid = 6
} ProjParameterIndices;
Parameters
Return Values
S_OK.
E_INVALIDARG, if the datum is incorrect.
Other errors, if a parameter in the array of variants has incorrect value.
Parameters
Return Values
S_OK.
E_INVALIDARG, if the method is incorrect.
Other errors, if a parameter in the array of variants has incorrect value.
Parameters
pVAl: Address of the current geographic unit (see GeographicUnits) of the system.
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;
Property (P)
Object IApplicationKeyRef functions
Method (M)
ApplicationKeyRef HRESULT IsFixedKey() M
HRESULT IsNetworkKey() M
HRESULT GetFskKeyRef([in] ULONG keyType, [out]
M
BSTR* reference)
HRESULT IsFixedKey();
Parameters
None
Return Values
HRESULT IsNetworkKey();
Parameters
None
Return Values
Parameters
Return Values
3.5.8.18.4 Example
CComPtr<IServiceProvider> pSrv;
GetSite(IID_IServiceProvider,(void**)&pSrv);
IApplicationKeyRefPtr pKeyRef;
HRESULT hr=pSrv->QueryService(SID_KEY_REF,__uuidof(IApplication
KeyRef),(void**)&pKeyRef);
CComBSTR str("You do not have a fixed key plugged.No ref available");
CComBSTR f=str;
if (hr==S_OK)
{
f=CComBSTR("Reference of fixed key :");
hr=pKeyRef->IsFixedKey();
if (hr==S_OK)
hr=pKeyRef->GetFskKeyRef(0,&str);
else
{
f=CComBSTR("Reference of floating key :");
hr=pKeyRef->GetFskKeyRef(1,&str);
}
f.Append(str);
}
else
str=CComBSTR("Impossible to find the reference of the key.");
Property (P)
Object ITraffic functions
Method (M)
Traffic HRESULT Source ([out, retval] IDispatch ** source) P
HRESULT ScenarioProvider ([out, retval] ITrafficS-
P
cenarioProvider ** ppProvider)
Parameters
Return Values
Parameters
Return Values
3.5.8.19.3 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))
{
// Found the traffic folder
IUnknownPtr pObject;
hr = pItem->get_Object(&pObject);
pTraffic = pObject;
break;
}
}
}
catch (...)
{
}
return pTraffic;
}
Property (P)
Object ITrafficScenarioProvider functions
Method (M)
HRESULT GetMeanSize ([in] VARIANT selectedMap-
TrafficScenarioProvider sNames,[in] double scale,[in] VARIANT re- P
served,[out, retval] ULONG *mobilesCount)
HRESULT Create ([in] VARIANT selectedMap-
sNames,[in] double scale,[in] AtoTrafficScenari-
P
oLaw 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: 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
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: Scale factor used in the determination of the mobiles count.
law: Probability law used to get a random count of mobiles, given the mean size of the
mobiles count.
reserved: Reserved for future use. Must be VT_EMPTY.
mobiles: Contains the mobiles data.
Return Values
Property (P)
Object Function
Method (M)
Traffic HRESULT Source([out,retval] IDispatch ** pSource); P
HRESULT ClassAttributes([out, retval] ITabularData
P
** ppTable);
HRESULT DefaultAttributes([out, retval] ITabularData
P
** ppTable);
Parameters
Return Values
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
Parameters
ppTable: Pointer to the default attributes of Traffic properties presented in a tabular data
manner. Currently no default attributes exist.
Return Values
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
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
end if
Next
end function
We recommend you to copy the code generated by the wizard (see 3.2.3 Step 3: Catching Events) when you want to imple-
ment connection points.
This section describes each default method created by the wizard and explains when it is called by Atoll.
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 <atlbase.h>
#undef ATL
namespace ATL = ::ATLFIX;
Parameters
evtStatus: Boolean set by the add-in to VARIANT_TRUE if Quit can continue or not.
Return Values
S_OK.
Parameters
document: Document interface pointer to the document object which has been opened.
Return Values
S_OK.
Parameters
Return Values
S_OK.
Parameters
Return Values
S_OK.
Parameters
document: Document interface pointer of the document object which has been successfully
saved.
Return Values
S_OK.
Parameters
document: Document interface pointer of the document object that has been successfully
created.
Return Values
S_OK.
Parameters
Return Values
S_OK.
Parameters
document: Document interface pointer of the document object which has been refreshed.
Return Values
S_OK.
Parameters
Return Values
S_OK.
Parameters
document: Document interface pointer of the document object which has been archived.
Return Values
S_OK.
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.
Parameters
document: Document interface pointer of the document object where the calculation were
performed.
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 auto-
connected add-ins only.
Fired when one licence token is acquired.
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
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 auto-
connected add-ins only.
Fired when one licence token is released.
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
Notes:
• Add-in connection status between two consecutive Atoll sessions is stored in the system registry from Atoll
version 2.4.0.
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).
Parameters
App: Application interface pointer of the top-level Application object, in which the add-in is
being loaded.
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: Boolean set by the add-in that returns VARIANT_TRUE if OnConnection succeeds,
otherwise, VARIANT_FALSE.
Return Values
S_OK.
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.
Notes:
• Read Shutting down Atoll to be sure to write a safe add-in.
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.
AFX_MANAGE_STATE(AfxGetStaticModuleState());
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.
3.5.11.2 AtoSaveChanges
Constant Value Description
atoSaveNo 0 Document is closed without being saved.
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.
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).
3.5.11.5 AtoWindowStatus
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).
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.
3.5.11.7 AtoCompareOp
Constant Value Description
atoEQ 0 (EQual) Specifies that the search is for the first value equal to searchVal.
(Strictly Lower Than) Specifies that the search is for the first value less
atoLT 1
than searchVal.
(Lower or Equal) Specifies that the search is for the first value less than or
atoLE 2
equal to searchVal.
(Greater or Equal) Specifies that the search is for the first value greater
atoGE 3
than or equal to searchVal.
(Strictly Greater Than) Specifies that the search is for the first value greater
atoGT 4
than searchVal.
(Not Equal) Specifies that the search is for the first value not equal to
atoNE 5
searchVal.
3.5.11.8 AtoTransmissionUnit
Constant Value Description
atoDbm 0 Transmission unit is dBm.
atoWatt 1 Transmission Unit is Watt.
atoKWatt 2 Transmission Unit is KWatt.
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.
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.
3.5.11.11 AtoRadiatedPowerUnit
Constant Value Description
atoRadiatedPowerEIRP 0 Radiated power is EIRP.
atoRadiatedPowerERP 1 Radiated power is ERP.
3.5.11.12 AtoAntennaGainUnit
Constant Value Description
atoAntennaGainDbi 0 Antenna gain unit is dBi.
atoAntennaGainDbd 1 Antenna gain unit is dBd.
3.5.11.13 AtoHeightOffsetUnit
Constant Value Description
atoHeightOffsetM 0 Height offset unit is metre.
atoHeightOffsetFeet 1 Height offset unit is feet.
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.
3.5.11.15 AtoRowFilter
Constants to filter only modified, added, or deleted rows.
3.5.11.16 AtoRowStatus
All possible row statuses.
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.
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.
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
3.5.12.2 Enumerations
typedef enum RasterDataType {fgUnsignedInteger = 0x100, fgInteger=0x200, fgRe-
al=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,
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:
• 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.
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.
Returns the value used by this coverage as an indicator meaning ‘no data available
get_NoDataValue
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.
Parameters
Return Values
Parameters
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.
Notes:
• 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.
Parameters
bounds: Receives the limits of the spatial domain for this coverage.
Return Values
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.
Parameters
Return Values
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 param-
eter 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:
• 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.
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.
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.
Returns the value used by this coverage as an indicator meaning ‘no data available
get_NoDataValue
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.
Parameters
Return Values
S_OK
Remark
This function will be called by Atoll only if the data really requires being drawn on the screen.
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 param-
eter 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.
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.
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[.
Return Values
Parameters
Return Values
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.
Parameters
Return Values
Parameters
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
Parameters
Return Values
Property (P)
Object IContextMenu functions
Method (M)
HRESULT GetCommandString(UINT_PTR idCmd, UINT
ContextMenu uFlags, UINT *pwReserved, LPSTR pszName, UINT M
cchMax);
Parameters
Return Values
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 identi-
fiers 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.
Parameters
struct _CMInvokeCommandInfo {
DWORD cbSize;
DWORD fMask;
HWND hwnd;
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(idOff-
set).
lpParameters: Not used.
lpDirectory: Not used.
nShow: Not used.
dwHotKey: Not used.
hIcon: Not used.
Return Values
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
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.
Contains “EMBEDDED” if storage is not external, else contains the
PATHNAME Char(255)
pathloss file name.
Contains a variant of VT_Unknown type, which is an IGridData interface.
PATHLOSS IUnknown
This grid data contains the Main pathloss matrix for transmitter TX_ID.
Contains a variant of VT_Unknown type, which is an IGridData interface.
SIGNAL IUnknown
This grid data contains the Main signal level matrix for transmitter TX_ID.
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:
• 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.
XIAfpNetworkData
XIAfpModel
XIAssignmentPlan XIPlanGenerator
XIDynamicGroupingScheme
XITrg
XIGroupingScheme
XIFrequencyBand
X(IQualityModel)
XIRadioTransmitter2
XItrgSeparations
XIInterfMatrix
XIAFPProgress
4.6.1.1 ALLOCATION_TYPE
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.
4.6.1.3 RESOURCE_TYPE
Constant Value Description
CHANNEL_TYPE 0
HSN_TYPE 1
MAIO_TYPE 2
BSIC_TYPE 3
CODE_TYPE 4 Not used.
4.6.1.4 ASSIGNMENT_MODE
Constant Value Description
Resource number can be assigned without grouping consideration,
FREE_ASSIGNENTa 0
but still with restriction to BAND or SUB-BAND limitations.
Resource numbers, which may be assigned to a cell, must belong to
GROUP_ASSIGNENT4 1
the same resource group whenever possible.
4.6.1.5 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)
TRG has been modified in at least one of the IRW_AssignmentPlan
MODIFIED 0x4
clone objects.
CREATED 0x8 TRX created by the AFP.
The ass_state varible may contain the following values depending on different cases:
Previous Approach
Case Current 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 HOPPING_MODE
Constant Value Description
NONE_FH 0 No Frequency Hopping.
BFH 1 BaseBand Frequency Hopping.
SFH 2 Synthesized Frequency Hopping.
4.6.1.7 AFP_RELATION_TYPE
Constant Value Description
COSITE 0x1
COCELL 0x2
NEIGHBOUR 0x4
SYNCHRO 0x8 Synchronised TRXs for MAIO management.
4.6.1.9 AFP_BASE_CONFIG
Structure containing default configuration information.
Parameters
Return Values
Parameters
Return Values
Parameters
Return Values
Parameters
Return Values
S_OK.
E_POINTER, if sep is NULL.
res is currently not used, CHANNEL_TYPE is assumed.
Parameters
Return Values
S_OK.
E_POINTER, if plan is NULL.
Parameters
Return Values
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.).
Parameters
Return Values
Parameters
Return Values
Parameters
Return Values
Parameters
Return Values
Parameters
Return Values
S_OK.
E_POINTER, if clone is NULL.
Parameters
Return Values
S_OK.
E_POINTER, if scheme is NULL.
Parameters
Return Values
S_OK.
Parameters
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)
Parameters
Return Values
S_OK.
E_INVALIDARG, in case trgIndx is incorrect.
HRESULT SetResource([in] RESOURCE_TYPE type, [in] int trgIndx, [in] int trx-
Number, [in] int res);
Parameters
Return Values
S_OK.
E_INVALIDARG, in case trgIndx is incorrect.
Parameters
Return Values
S_OK.
E_POINTER, if id is NULL.
Parameters
Return Values
S_OK.
(count = NULL is not supported)
Parameters
Return Values
S_OK or E_INVALIDARG.
(size = NULL is not supported)
Parameters
Return Values
S_OK or E_INVALIDARG.
(numbers = NULL is not supported)
Checks that count is exactly the group size.
Parameters
Return Values
Parameters
Return Values
S_OK.
(grpIndx = NULL is not supported)
HRESULT SetGrp([in] int grpIndx, [in] int grpSz, [in, size_is(grpSz)] int *num-
bers);
Parameters
Return Values
S_OK.
E_INVALIDARG,if there is a problem with grpIndx or grpSz.
(numbers = NULL is not supported)
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:
• AFP model must delete groups that are no longer assigned in RW_IAssignmentPlan clone to free memory.
Parameters
Return Values
S_OK.
(indx = NULL is not supported)
Parameters
trxType: The TRX type of the TRG (BCCH, TCH , TCH_INNER, etc).
Return Values
S_OK.
(trxType = NULL is not supported)
HRESULT ContainsBroadcastChannel();
Parameters
None.
Return Values
Parameters
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.
Parameters
Return Values
S_OK.
E_POINTER, if fb is NULL.
Parameters
Return Values
Parameters
Return Values
S_OK.
E_POINTER, if traffic is NULL.
Parameters
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:
• TCH with no DTX and no AMR-HR → 1
• TCH with DTX → 0.7
• TCH with DTX and AMR-HR → 0.65
Parameters
Return Values
S_OK.
(factor = NULL is not supported)
Parameters
Return Values
S_OK.
E_POINTER, if mode is NULL.
Parameters
Return Values
S_OK.
E_POINTER, if mode is NULL.
Parameters
Return Values
S_OK.
E_POINTER, if sz is NULL.
Parameters
Return Values
Parameters
Return Values
Parameters
Return Values
Parameters
tr: Transmitter.
Return Values
S_OK.
E_POINTER, if tr is NULL.
Parameters
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.
Parameters
Return Values
S_OK.
E_POINTER, if minProba is NULL.
Parameters
factor: Number of time slots on a physical carrier (e.g. 8 for GSM, 3 for some other TDMA
systems, etc).
Return Values
S_OK.
E_POINTER, if factor is NULL.
Parameters
Return Values
S_OK.
E_POINTER, if widthInChannels is NULL.
Parameters
n: Adjacency level.
asupp: Suppression value in dB.
Return Values
HRESULT GetSeparation( [in] int type, [in] int trg1, [in] int trg2, [out] int*
sep);
Parameters
Return Values
S_OK.
E_POINTER, if sep is NULL.
E_FAIL, if there was a problem while loading the separations table.
HRESULT GetDefaultSeparation( [in] int type, [in] int trg, [out] int* sep);
Parameters
Return Values
HRESULT GetRelationsCount( [in] int type, [in] int trg, [out] int* count);
Parameters
Return Values
S_OK.
E_POINTER, if count is NULL.
E_FAIL, if there was a problem while loading the separations table.
HRESULT GetRelation( [in] int type, [in] int trg1, [in] int indx, [out] int*
trg2, [out] int* sep);
Parameters
Return Values
S_OK.
E_POINTER, if trg2 or sep is NULL.
E_FAIL, if there was a problem while loading the separations table.
Parameters
Return Values
S_OK.
E_POINTER, if nThresh is NULL.
HRESULT GetInterferingHistogram( [in] int trgv, [in] int trgi, [in] int max-
Count, [out] int* count, [out, size_is(maxCount)] float* thresholds, [out,
size_is(maxCount)] float* probas);
Parameters
Return Values
HRESULT GetInterferingProbability( [in] int trgv, [in] int trgi, [in] float
CI_threshold, [out] float* proba);
Parameters
Return Values
S_OK.
E_POINTER, if proba is NULL.
Parameters
Return Values
S_OK.
E_POINTER, if count is NULL.
Parameters
Return Values
S_OK.
S_FALSE, if count is different from the actual count of interferers.
E_POINTER, if trgi is NULL.
Parameters
Return Values
S_OK.
E_POINTER, if count is NULL.
HRESULT GetVictims ( [in] int trgi, [in] int count, [out,size_is(count)] int*
trgv);
Parameters
Return Values
S_OK.
HRESULT GetInterfererHistogram( [in] int trgv, [in] int indx, [out] int* trgi,
[in] int maxCount, [out] int* count, [out, size_is(maxCount)] float* thresh-
olds, [out, size_is(maxCount)] float* probas);
Parameters
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.
Parameters
None.
Return Values
S_OK.
Parameters
Return Values
Parameters
Return Values
S_OK.
Parameters
Return Values
S_OK.
Parameters
Return Values
S_OK.
Parameters
Return Values
S_OK.
Parameters
Return Values
S_OK.
(planGenerator = NULL is not supported)
Parameters
Return Values
S_OK.
E_FAIL in case of problem.
(No parameter can be NULL)
Parameters
Return Values
S_OK.
E_FAIL in case of problem.
(No parameter can be NULL)
Parameters
parent: HWND of the parent to which the model must relate its config dialog(s).
Return Values
S_OK.
// 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:
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.
Notes:
• See section 4.6.1.5.1 for more details on the TO_ASSIGN and FROZEN assignment states.
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.
// 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 *net, int trg,int channel,int
*groupIndx)
{
// Getting the scheme
// -------------------
ITrg *p_trg;
IgroupingScheme *p_scheme;
net->GetTrg(trg, &p_trg);
P_trg->GetScheme(CHANNEL_TYPE,&p_scheme);
// Scanning groups
// ---------------
*groupIndx = -1;
int groupCount;
p_scheme->GetGroupCount(&groupCount);
for(int grp=0;grp<groupCount;grp++)
{
HRESULT res =p_scheme->Contains(grp, );
If(res == S_OK)
{
*grpIndx=grp;
return TRUE;
}
}
return FALSE;
}
The interface IDynamicGroupingScheme is derived from IGroupingScheme and is used for the storage of MALs (channels
lists) of the TRGs with SFH having FREE_ASSIGNMENT mode. In this case, the MALs used are free and are all stored
in the temporary Dynamic group scheme provided by the function GetFreeMALScheme of the IAssignmentPlan interface.
See 4.7.7 Working with Several Assignment Plans for an example using dynamic scheme.
4.7.6.1 Example
(victim trg = trgv, interferer trg = trgi)
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 opti-
mised access, avoiding the necessity to scan all TRGs. This optimised access is similar to the one provided for ITrgSep-
arations.
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.
// 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; // read only
IRW_AssignmentPlan* current=0; // 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;
}
// Example
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:
If the AFP must remove any TRX, it will use the method RemoveTrx(), still considering that it should not remove Frozen
TRXs.
Notes:
• 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.
// --------------------------------------------------------------------------
// Example: function providing the minimal channel distance between a given TRG
// and a channel value. (If this minimal channel distance is smaller than 1 then
// a Co-channel reuse exists, if it is 1 than an adj-channel reuse exists …)
// --------------------------------------------------------------------------
#define MAX_MAL_SIZE 1024
int GetChannelDistance(IAssignementPlan *plan,ITrg *p_trg,int channel)
{
int minDist= 1000; // prefer MAX_INT
// retrieve some useful information
// -------------------------------
HOPPING_MODE hopMode;
p_trg->GetHoppingMode(&hopMode);
ASSIGNMENT_MODE assignMode;
p_trg->GetAssignmentMode(&assignMode) ;
int trgIndx;
p_trg->GetIndex(&trgIndx);
// find associated grouping scheme
// --------------------------------
IGroupingScheme *p_gs=0;
If(hopMode!=SFH)
p_trg->GetGroupingScheme(CHANNEL_TYPE,&p_gs);
else
plan->GetFreeMALScheme(&p_gs);
// loop on TRXs
// ------------
int trxCount;
plan->GetTrx(&trxCount);
int previousResource=-1;
for(int trx=0;trx<trxCount;trx++)
{
int resource;
plan->GetResource(CHANNEL_TYPE,trgIndx,trx,&resource);
if(resource==previousResource)
continue; // case of a MAL shared by all TRXs
previousResource= resource;
if(hopMode!=SFH)// mode NONE_FH or BBH
minDist= min(minDist,ABS(channel-res)); // res is a channel value
else // res refers to a MAL
{
// Get MAL of this trx
// -------------------
int malSize=0;
p_gs->GetGroupSize(resource, &malSize);
if(malSize>MAX_MAL_SIZE)
error(“Size of MAL bigger than supported by MyAFP”);
int mal[MAX_MAL_SIZE];
p_gs->GetResourceNumbers(resource, malSize,mal);
// Loop on channel list of this TRX
// --------------------------------
for(indxInMal =0;indxInMal <malSize; indxInMal ++)
{
minDist = min(minDist,ABS(mal[indxInMal]-channel));
}
p_gs->Release();
}
}
return minDist;
}
_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.
}
resources->AddStandardResourceTypes(HSN_ALLOC|MAIO_ALLOC);
…
Notes:
• Resources is always set to NULL (not used).
Caution:
• 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.
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);")
//---------------------------------------------------------------------------
----------
// 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;
}
//---------------------------------------------------------------------------
----------
// Advanced interface : IAfpModel2
//---------------------------------------------------------------------------
----------
//interface ISpecifyPropertyPages;
//interface IPlanEvaluator;
[
uuid(44B91C99-46EF-41be-8D94-777A0DA669F7),
helpstring("IAfpModel Interface"),
pointer_default(unique)
]
// ------------------------
// Resources support
// ------------------------
HRESULT GetResourceCapabilities([in] IResourceTypesCollection* support-
edResourceTypes);
// ------------------------
// Scenario suppport
// ------------------------
HRESULT SupportsScenario([out] int *scenarioCount); // return S_OK if
support
HRESULT GetScenario([in] int indxScenario
,[in] 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
{
}
// --------------------------------------------------------------------------
---------
[
uuid(A902215E-010D-4423-87C5-A8978CA1DE1D),
helpstring("IAfpConfigure Interface"),
pointer_default(unique)
]
interface IAfpConfigure : IUnknown // to be implemented by AFP if it
requires
{ // 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
//
=============================================================================
======
// 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"),
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; // access to properties of one BTS Trx group (pool
of TRXs)
interface ITrgSeparations; // access to predefined separation requirements
between TRX groups
//---------------------------------------------------------------------------
----------
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)
]
interface IAfpNetworkData: IUnknown
{
//---------------------------------------------------------------------------
----------
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
{
// 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; // read access to grouping scheme (list of
resource groups)
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
{ // Means :
TO_ASSIGN = 0x1, // TRXs or TRGs selected for assignment (for a certain
resource type)
FROZEN = 0x2, // TRXs or TRGs forbidden for assignment (for a certain
resource type)
MODIFIED = 0x4, // TRXs or TRGs for which a certain resource type was
assigned.
CREATED = 0x8 // this TRX was created by the AFP (remark: TRGs can not
be created!!)
} 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 = 0x8, // relation specify synchronized TRXs for MAIO man-
agement
SPECIAL = 0x10, // for exceptional relations (eg: separation exception)
COTRG = 0x20 // (in some cases inter-trg separations can be higher
then others)
} 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 // Access to a trx group
//----------------------------------------------------------
{
HRESULT GetIndx([out] int *indx); // indx of the TRX-group
// in the AfPNetworkData
HRESULT GetTrxType([out] BSTR* trgType); // examples:
"BCCH","TCH","TCH_Inner".
HRESULT ContainsBroadcastChannel(); // S_OK => true, S_FALSE => false
HRESULT GetGroupingScheme( // allowed GS for allocation
[in] 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
// Quality Target:
// ==============
// HRESULT GetQualityModel([out] IQualityModel** qm); => Future use
HRESULT GetQualityThreshold( // return E_NOTIMPL =>metric
unsupported
[out] QUALITY_METRIC *metric, // unit of qmin (default= CI)
[out] float* qmin); // min value of quality required
HRESULT GetProbabilityThreshold(
[out] float* minProba);
}
//---------------------------------------------------------------------------
-----------------
[
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
//--------------------------------------------------------------------------
------------------
[
uuid(24A57CA7-4F33-ED32-8934-2434A3B71AC2),
helpstring("IAfpTransmitter Interface"),
pointer_default(unique)
]
//----------------------------------------------------------
interface IAfpTransmitter: IRadioTransmitter2 // Access to a the basic trans-
mitter 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);
}
//---------------------------------------------------------------------------
-----------------
//---------------------------------------------------------------------------
----------
// 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
// -----------------------------------------------------
// read of resource number at Trx & TrxGroup level
// -----------------------------------------------------
// if the Hopping mode of the trx group is "SFH" and resource type is
CHANNEL_TYPE
// res refers to the group number of the MAL scheme (see following
method)
//
// In all other cases res is the resource number (ARFCN, HSN, MAIO, BSIC,
...)
//----------------------------------------------------------------------
-------------
HRESULT GetResource(
[in] RESOURCE_TYPE type,
[in] int trgIndx, // indx of the trx group
[in] int 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 resourceIndx,// obtained from IResourceTypesCol-
lection::GetCustomResource
[in] int 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 trxNumber,
// Trx edition
//---------------------------------------------------------
HRESULT AddTrxs([in] int trgIndx,
[in] short newTrxCount,
[out, size_is(newTrxCount)] int* newTrx-
Numbers);
// 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
//---------------------------------------------------------------------------
-----------------
[
uuid(2A98605E-F255-48a3-9ABD-7BFD4B4C80AF),
helpstring("IRW_AssignmentPlan2 Interface"),
pointer_default(unique)
]
interface IRW_AssignmentPlan2: IUnknown
{
HRESULT SetCustomResource(
[in] int resourceId, //Can be a custom resource
[in] int 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 trxNumber, //N° of trx in the transmitter (use -1 for
Trg level access)
[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 co-
site 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( // #
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 GetFullSeparationInfo(
[in] int type, // combination different 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 Con-
trol)
{
//
HRESULT GetHistogramSize(
[in] int trgv, // trg indx of victim
[out] int* nThresh); // in order to dimension histograms
[
uuid(10C64AA3-9B6C-4A8C-BA5A-D907F668BD84),
helpstring("IGroupingScheme Interface"),
pointer_default(unique)
]
==================================================
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
}
Release 2.6.0
AT260_DRG_E0
7 rue des briquetiers – 31700 – Blagnac – France
February 2007
Tel: +33 (0)5 62 74 72 10 – Fax: +33 (0)5 62 74 72 11
http://www.forsk.com