Defining a COM Object's Interface
Go Up to Creating Simple COM Servers Index
When you use a wizard to create a COM object, the wizard automatically generates a type library (unless you specify otherwise in the COM object wizard). The type library provides a way for host applications to find out what the object can do. It also lets you define your object interface using the Type Library Editor. The interfaces you define in the Type Library editor define what properties, methods, and events your object exposes to clients.
Note: If you selected an existing interface in the COM object wizard, you do not need to add properties and methods. The definition of the interface is imported from the type library in which it was defined. Instead, simply locate the methods of the imported interface in the implementation unit and fill in their bodies.
Contents
Adding a property to the object interface
When you Adding Properties and Methods to the Type Library to your object interface using the Type Library Editor, it automatically adds a method to read the value of the property and/or a method to set the value of the property. The Type Library Editor, in turn, adds these methods to your implementation class, and in your implementation unit creates empty method implementations for you to complete.
To add a property to your object interface
- In the Type Library Editor, select the default interface for the object.The default interface should be the name of the object preceded by the letter "I." To determine the default, in the Type Library Editor, click the CoClass and then select the Implements tab, and check the list of implemented interfaces for the one marked, "Default."
- To expose a read/write property, click the New Property button on the toolbar; otherwise, click the arrow next to the New Property button on the toolbar, and then click the type of property to expose.
- In the Attributes pane, specify the name and type of the property.
- On the Type Library Editor toolbar, click the Refresh Implementation button.A definition and skeletal implementations for the property access methods are inserted into the object's implementation unit.
- In the implementation unit, locate the access methods for the property. These have names of the form Get_PropertyName and Set_PropertyName. Add code that gets or sets the property value of your object. This code may simply call an existing function inside the application, access a data member that you add to the object definition, or otherwise implement the property.
Adding a method to the object interface
When you add a method to your object interface using the Type Library Editor, the Type Library Editor can, in turn, add the methods to your implementation class, and in your implementation unit create empty implementation for you to complete.
To expose a method via your object interface
- In the Type Library Editor, select the default interface for the object.The default interface should be the name of the object preceded by the letter "I". To determine the default, in the Type Library Editor, click the CoClass and select the Implements tab, and check the list of implemented interfaces for the one marked, "Default."
- Click the New Method button.
- In the Attributes pane, specify the name of the method.
- In the Parameters pane, specify the method's return type and add the appropriate parameters.
- On the Type Library Editor toolbar, click the Refresh Implementation button.A definition and skeletal implementation for the method is inserted into the object's implementation unit.
- In the implementation unit, locate the newly inserted method implementation. The method is completely empty. Fill in the body to perform whatever task the method represents.
Exposing events to clients
There are two types of events that a COM object can generate: traditional events and COM+ events.
- COM+ events require that you create a separate event object using the event object wizard and add code to call that event object from your server object.
- You can use the wizard to handle much of the work in generating traditional events. This process is described below.
Note: The COM object wizard does not generate event support code. If you want your object to generate traditional events, you should use the Automation object wizard.
In order for an object to generate events, you need to do the following:
- In the Automation Object wizard, check the box, Generate event support code.The wizard creates an object that includes an Events interface as well as the default interface. This Events interface has a name of the form ICoClassnameEvents. It is an outgoing (source) interface, which means that it is not an interface your object implements, but rather is an interface that clients must implement and which your object calls. (You can see this by selecting your CoClass, going to the Implements page, and noting that the Source column on the Events interface says true.)In addition to the Events interface, the wizard adds the IConnectionPointContainer interface to the declaration of your implementation class, and adds several class members for handling events. Of these new class members, the most important are FConnectionPoint and FConnectionPoints, which implement the IConnectionPoint and IConnectionPointContainer interfaces using built-in VCL classes. FConnectionPoint is maintained by another method that the wizard adds, EventSinkChanged.
- In the Type Library Editor, select the outgoing Events interface for your object. (This is the one with a name of the form ICoClassNameEvents)
- Click the New Method button from the Type Library Editor toolbar. Each method you add to the Events interface represents an event handler that the client must implement.
- In the Attributes pane, specify the name of the event handler, such as MyEvent.
- On the Type Library Editor toolbar, click the Refresh Implementation button.Your object implementation now has everything it needs to accept client event sinks and maintain a list of interfaces to call when the event occurs. To call these interfaces, you can create a method to generate each event on clients.
- In the Code Editor, add a method to your object for firing each event. For example:
unit ev;
interface
uses
ComObj, AxCtrls, ActiveX, Project1_TLB;
type
TMyAutoObject = class (TAutoObject,IConnectionPointContainer, IMyAutoObject)
private
.
.
.
public
procedure Initialize; override;
procedure Fire_MyEvent; { Add a method to fire the event}
- Implement the method you added in the last step so that it iterates through all the event sinks maintained by your object's FConnectionPoint member:
procedure TMyAutoObject.Fire_MyEvent;
var
I: Integer;
EventSinkList: TList;
EventSink: IMyAutoObjectEvents;
begin
if FConnectionPoint <> nil then
begin
EventSinkList :=FConnectionPoint.SinkList; {get the list of client sinks }
for I := 0 to EventSinkList.Count - 1 do
begin
EventSink := IUnknown(FEvents[I]) as IMyAutoObjectEvents;
EventSink.MyEvent;
end;
end;
end;
Whenever you need to fire the event so that clients are informed of its occurrence, call the method that dispatches the event to all event sinks:
If EventOccurs then Fire_MyEvent; { Call method you created to fire events.}
if (EventOccurs) Fire_MyEvent; // Call method you created to fire events.