The Host Interface

When a FreeFlyer Extension is loaded and initialized by FreeFlyer it is given an instance of the IFFHost interface. This gives the Extension access to FreeFlyer's error reporting mechanisms, various conversion routines, and other resources. Specifically, the host interface gives you access to:

•Attitude Conversion (IAttitudeConverter)

•Element Set Conversion (IElementSetConverter)

•Time Conversion (ITimeConverter)

•Solar System Information (ISolarSystem)

•Error Message Reporting (the ReportErrorMessage method)

Additionally the host interface allows you to initialize IMatrix and ITimeSpan classes through:

•Matrix Creation

oThe CreateMatrix method

•TimeSpan Creation

oThe CreateTimeSpanQuantized and CreateTimeSpanUnquantized methods

Using the Host Interface

When you create your own Extension, this interface can be accessed through the inherited Host property. Below is an example of how these interfaces might be used:

public void GetEarthSunVectorAtEpoch(ITimeSpan epoch, double [] vector)

{

double [] earthPos;

double [] sunPos;

Host.SolarSystem.Earth.GetPositionAtEpoch(epoch, out earthPos);

Host.SolarSystem.Sun.GetPositionAtEpoch(epoch, out sunPos);

vector[0] = sunPos[0] - earthPos[0];

vector[1] = sunPos[1] - earthPos[1];

vector[2] = sunPos[2] - earthPos[2];

}

In this example, the Solar System interface is used to obtain the ICRF positions of Earth and the Sun at the input epoch. Then, the difference of the two positions is computed to find the components of the relative position vector. Please refer to the Programming Reference for full details on the available interfaces through IFFHost.

IMatrix Creation

When working with IMatrix objects, the first step is to create the object and set it to null:

Then, the IMatrix object should be initialized in an override of the IFFObjectExtension.Initialize method using the IFFHost.CreateMatrix method:

public override void Initialize(IFFHost host, IFFObject baseObject)

{

base.Initialize(host, baseObject);

// Finish creating the IMatrix object:

_myMatrix = host.CreateMatrix();

}

Once this step is complete the IMatrix object can be used as desired within your extension.

ITimeSpan Creation

The workflow for creating and using ITimeSpan objects is similar to that for IMatrix objects. The first step is to create the object and set it to null:

Then, the ITimeSpan object should be initialized in an override of the IFFObjectExtension.Initialize method:

public override void Initialize(IFFHost host, IFFObject baseObject)

{

base.Initialize(host, baseObject);

// Finish creating the ITimeSpan object:

_myTimeSpan = host.CreateTimeSpanQuantized();

// or

_myTimeSpan = host.CreateTimeSpanUnquantized();

}

For the ITimeSpan, there are two methods to do this: IFFHost.CreateTimeSpanQuantized and IFFHost.CreateTimeSpanUnquantized. As the method names state, the CreateTimeSpanQuantized method creates a quantized TimeSpan and the CreateTimeSpanUnquantized method creates an unquantized TimeSpan. The difference between the two is the precision to which they can hold time: a quantized TimeSpan holds time precisely to the nanosecond level whereas an unquantized TimeSpan holds time to the maximum available precision, which permits sub-nanosecond precision. An unquantized TimeSpan is typically only needed when implementing the CalculateForce method in a Custom Force Extension, as sub-nanosecond precision is needed to sample accelerations at different stages of the integration process. Once this step is complete the ITimeSpan object can be used as desired within your extension.