Overview of API Architecture

The Reflection 2008 application programming interface (API) is built on Microsoft .NET technology, and as a result, takes advantage of its many benefits. This API exposes many functions programmatically for the first time, providing a whole range of opportunities for creating rich custom applications. For example, you can now integrate Web browser and Productivity features into your host applications.

Where do I start?

The MyReflection object is the starting point of the API and has methods you can use to create Application objects. An Application object represents a single Reflection 2008 instance. You can create Application objects for as many Reflection 2008 instances as you want to work with. MyReflection also includes methods that you can use to start a Reflection 2008 instance (if one isn't already running) and to stop a Reflection 2008 instance started by your program.

In most cases, you'll create one Application object for each Reflection 2008 instance. You can keep this Application object instance around and refer to it in your application. After you create an Application object, you can get other objects from the Application that represent major functional areas in Reflection 2008. For example, you can get a Frame object to work with a user interface.

Targeting Reflection 2008 instances

By using the CreateApplication( ) method (of MyReflection) with the appropriate API port number or the IPC channel name, you can create an Application object for a Reflection 2008 instance on the local computer. (API port and IPC channel settings are located in the Set Up API and Macro Security dialog box in Reflection 2008.)

To create an Application object for a Reflection 2008 instance that is running on a remote computer, use the CreateApplication( ) method with the TCP/IP address and API port number for the remote computer. The Reflection 2008 instance must be configured to accept remote API calls (see Access Reflection 2008 Remotely).

Accessing session data

A control represents the data aspect of an opened Reflection 2008 document and can take many forms, such as an IbmTerminal or WebControl. By calling the CreateControl( ) method on an Application object, you can create a new session or Web document. Several different CreateControl( ) methods exist for you to use in different scenarios. (Similarly, you can get a control for a document that's already running by using the GetControl( ) method.)

To identify and get controls from existing documents, you can use the instance ID, the name, or the file path of the underlying document. The name property of a control is initially empty. You can leave it blank or set it to the identifier you want. However, the name property does not persist after you close the session document.

Interacting with UI elements

A Frame is another type of object that you can get from the Application object. The Frame object is the user interface aspect of Reflection 2008. It provides methods and properties for working with Views (the visible aspect of a session or Web document), and for working with the state, position, and dimensions of the Reflection 2008 main window (which is called the workspace).

When you get or create a new control, it isn't visible initially. To make the control visible, you must create a View object that is associated with the control (View objects always include a single embedded control). You don't necessarily need a View to interact with a document (for example, to get or send data to a host application), and omitting the View can reduce the resource overhead.

You can identify a View the same way that you identify controls: by the instance ID, the name, the title text, or the file path of the underlying session document. The name property of a View is initially empty; you can set this property to any string to help identify the View object later.

Note: In the likelihood that multiple Views and controls will be created from a single document, you should use a unique identifier (such as the instance ID) to identify a particular View or control. For more information, see Getting Terminal and View Objects.

Working with events

The Reflection 2008 API supports a variety of programming event models. Many objects support asynchronous .NET events. Alternately, several synchronous wait methods are also available; these methods wait for specified conditions to happen. Other options for synchronous event handling include runtime status properties that provide the state information of their associated objects, such as the IsConnected property on the IbmTerminal object.

For information about Reflection objects and their methods, properties, and events, see the Reflection 2008 .NET API Help. For a description of the namespaces in the Reflection 2008 API, see Appendix A in this guide.