Handling Events

An event is a way to notify an application that a specified action has occurred in the host session so that the application can respond accordingly. In the Attachmate Verastream SDK for Unisys and Airlines, the Screen object receives an event from the host session, and then passes the event to the application.

The SDK provides support for the following events that can occur during a host session or that are generated by the transport:

To use events in your application, your Screen object must implement the appropriate event interfaces. For host session events, use IScreenListener (for Java), IScreenListenerEx (for COM), or ScreenUPG delegates (for .NET). For transport events, use IStatusListener (for Java and COM) or ScreenUPG delegates (for .NET).

Once you have implemented the proper interface, you can use the Screen object's screen listener methods to add event listening capabilities to your application. The Screen object provides six methods for event handling, two that are specific to Java-based applications and four that are specific to COM/.NET-based applications:

• Java—addIScreenListener and removeIScreenListener

  Each of these methods takes an IScreenListener or IStatusListener listener.

• COM—addIScreenListenerEx, removeIScreenListenerEx, addIStatusListener, and removeIStatusListener

  Each of these methods takes a pointer to a Dispatch that implements the screen listener interface.

  The COM-based event support provided in the SDK is specific to Microsoft Visual C++ 6.0.

• .NET—addIScreenListenerEx, removeIScreenListenerEx, addIStatusListener, and removeIStatusListener

  Each of these events takes a null parameter. Calling the methods either enables or disables the generation of the events.

  To process the events, a ScreenUPG delegate must be created pointing to a function to handle the event, as follows:

  • onScreenChangedHandler()

  • onConnectionLostHandler()

  • onErrorHandler()

  • onScreenShapeChangedHandler()

  • onLostRemoteWindowHandler()

  • onStatusReceivedHandler(short status, ref string details)

Details on coding events for each of these environments are provided in the following sections:

• Handling Events in Java

• Handling Events in Visual C++

• Handling Events under .NET in C#

• Handling Events under Visual Basic

It is very important that the code in your event handlers does as little processing as possible so that the callback can return quickly to the SDK objects. Never call a Screen object method from inside an event handler method.

Handling Events in Java

Handling Events in Visual C++

Adding event support in Visual C++ is a bit more complex than in Java, so each of the major tasks is broken down into individual steps. If you are using Microsoft Foundation Classes (MFC) and your class derives from CCmdTarget, you can use ClassWizard to do much of the work. If your class derives from CWinThread, however, it must be added manually; the code for doing so is provided in the following procedure.

Complete the following major tasks to add event support to your Visual C++ application:

1. Set up the class to receive events.

2. Register and de-register the class with the screen object.

3. Initialize OLE.

Handling Events under .NET in C#

class Program
{
public ScreenUPG.ScreenUPG screen;
      public Program instance = new Program();

      // Delegate handlers
      public ScreenUPG.ScreenUPG.onConnectionLostHandler myConnectionLostHandler;
      public ScreenUPG.ScreenUPG.onScreenChangedHandler myScreenChangedHandler;
      public ScreenUPG.ScreenUPG.onScreenChangedHandler myScreenShapeChangedHandler;
      public ScreenUPG.ScreenUPG.onLostRemoteWindowHandler myLostRemoteWindowHandler;
      public ScreenUPG.ScreenUPG.onErrorHandler myErrorHandler;
      public void onScreenChanged()
      {
            ....// TODO: Place your code here
      }

      public void onConnectionLost()
      {
            ....// TODO: Place your code here
      }

      public void onError()
      {
            ....// TODO: Place your code here
      }

      public void onScreenShapeChanged()
      {
            ....// TODO: Place your code here
      }

      public void onLostRemoteWindow()
      {
            ....// TODO: Place your code here
      }

      static void Main(string[] args)
      {
            SessionLoader.SessionLoader sl = new SessionLoader.SessionLoader();
            string xmlConfig = "your host XML configuration";
            screen = sl.requestScreenEx("", "", xmlConfig, 0);
            if (screen != null)
            {
                  // Setup the delegates
                  instance = new Program();
                  myConnectionLostHandler = new ScreenUPG.ScreenUPG.onConnectionLostHandler(instance.onConnectionLost);
                  screen.onConnectionLost += myConnectionLostHandler;
                  myScreenChangedHandler = new ScreenUPG.ScreenUPG.onScreenChangedHandler(instance.onScreenChanged);
                  screen.onScreenChanged += myScreenChangedHandler;
                  myScreenShapeChangedHandler = new ScreenUPG.ScreenUPG.onScreenShapeChangedHandler(instance.onScreenShapeChanged);
                  screen.onScreenShapeChanged += myScreenShapeChangedHandler;
                  myLostRemoteWindowHandler = new ScreenUPG.ScreenUPG.onLostRemoteWindowHandler(instance.onLostRemoteWindow);
                  screen.onLostRemoteWindow += myLostRemoteWindowHandler;
                  myOnErrorHandler = new ScreenUPG.ScreenUPG.onErrorHandler(instance.onError);
                  screen.onError += onErrorHandler;

                  // Register a listener and it's delegates
                  screen.addIScreenListenerEx(null);

                  // Open host connection
                  if (screen.Open())
                  {
                        ....// TODO: Place your code here
                  }
            }
      }
}

Handling Events under Visual Basic

Dim WithEvents screen As ScreenUPG.ScreenUPG

Private Sub screen_onConnectionLost()
'TODO: Place your code here
End Sub

Private Sub screen_onError()
'TODO: Place your code here
End Sub

Private Sub screen_onScreenChanged()
'TODO: Place your code here
End Sub

Private Sub screen_onScreenShapeChanged()
'TODO: Place your code here
End Sub

Private Sub screen_onLostRemoteWindow()
'TODO: Place your code here
End Sub

Private Sub addScreenListener()
screen.addIScreenListenerEx screen
End Sub

	Common Tasks
	The Screen Object Model
	Handling Exceptions