Accessing the Controller

Overview

Making use of controller functionality requires special attention. Disposal of Controller API objects when closing a view or the entire application is vital to save memory. Another pitfall that must be avoided is updating the user interface on a worker thread.

Controller instance

Before accessing the controller functionality you need to instantiate the Controller object. The best place to do this is normally in the Install method, which is called by TAF after the constructor of your view class has executed.

The Controller declaration should be done on class scope level:

Copy

private Controller aController;

Copy

Private AController As Controller

The recommendation is to instantiate the Controller object in the Install method:

Copy

aController = new Controller();

Copy

AController = New Controller

Using the Controller object you can access I/O signals, RAPID data variables, event log messages and so on. Most of these objects will be created explicitly and should be disposed of explicitly.

Note
Avoid placing any code that may result in an exception before the method InitializeComponent. Then at least you have a user interface, where you can display a MessageBox with information about what went wrong.

Note
It is recommended that if several classes need to access the controller, they all reference the same Controller object.

Subscribing to controller events

The Controller object provides several public events, which enable you to listen to operating mode changes, controller state changes, mastership changes and so on.

Copy

AController.OperatingModeChanged += new OperatingModeChangedEventHandler(UpdateOP);
 AController.MastershipChanged += new MastershipChangedEventHandler(UpdateMast);
 Controller.BackupFinished += new BackupFinishedEventHandler(UpdateBack);
 Controller.StateChanged += new StateChangedEventHandler(UpdateState);

Copy

AddHandler AController.OperatingModeChanged, AddressOf UpdateOP
AddHandler AController.StateChanged, AddressOf UpdateState
AddHandler AController.MastershipChanged, AddressOf UpdateMast
AddHandler AController.BackupFinished, AddressOf UpdateBack

Note
Controller events use their own threads. Study Controller events and threads to find out how to avoid threading conflicts.

Caution
Do not rely on receiving an initial event when setting up/activating a controller event. There is no guarantee an event will be triggered, so you had better read the initial state from the controller.

Creating a backup

Using the Controller object you can call the Backup method. The argument is a string describing the directory path on the controller where the backup should be stored. As the backup process is performed asynchronously you can add an event handler to receive a BackupCompleted event when the backup is completed.

Copy

string backupDir = "(BACKUP)$"+backupDirName;
this.aController.BackupCompleted += new BackupEventHandler(controller_BackupCompleted);
this.aController.Backup(backupDir);

Copy

Dim BackupDir As String = "(BACKUP)$"+BackupDirName
AddHandler Me.AController.BackupCompleted, AddressOf AController_BackupCompleted)
Me.AController.Backup(BackupDir)

Note
There is also a Restore method available. The Reference Manual FlexPendant SDK is the complete FlexPendant SDK programming guide and is more detailed than this manual. For the Backup and Restore methods, for example, there are parameter descriptions, remarks, code examples and so on.

Dispose

The disposal of the Controller object should be done in the Uninstall or Dispose method of the application view class.

Make a check first that disposal has not already been done. Do not forget to remove any subscriptions to controller events before the Dispose() call:

Copy

if (aController != null)
{
aController.OperatingModeChanged -= new OperatingModeChangedEventHandler(OpMChange);
aController.Dispose();
aController = null;
}

Copy

 If Not AController Is Nothing Then
 RemoveHandler AController.OperatingModeChanged, AddressOf OpMChange
 AController.Dispose()
AController = Nothing
 End If

Caution
VB programmers should be aware that it is a bit tricky to use WithEvents together with the Dispose pattern on the .NET platform. When you use WithEvents the .NET framework automatically removes any subscriptions when the object is set to Nothing. If you look at the code preceding sample, which does NOT use WithEvents, you will understand why such behavior causes problems. When the controller reference is set to Nothing and the .NET framework tries to remove its subscription, the internal controller object has already been removed by the Dispose call in the preceding statement, and a NullReferenceException is thrown. This is not specific to the FlexPendant SDK, but a Microsoft issue. To avoid it you are advised to use AddHandler and RemoveHandler like in the example.

Caution

VB programmers should be aware that it is a bit tricky to use WithEvents together with the Dispose pattern on the .NET platform. When you use WithEvents the .NET framework automatically removes any subscriptions when the object is set to Nothing.

If you look at the code preceding sample, which does NOT use WithEvents, you will understand why such behavior causes problems. When the controller reference is set to Nothing and the .NET framework tries to remove its subscription, the internal controller object has already been removed by the Dispose call in the preceding statement, and a NullReferenceException is thrown. This is not specific to the FlexPendant SDK, but a Microsoft issue. To avoid it you are advised to use AddHandler and RemoveHandler like in the example.