Online Eiffel Documentation
EiffelStudio

Accessing a COM component

The third tutorial describes how to access a COM component. It will build a client of the StringManipulator component built in the first tutorial.

Step by step instructions

  1. In Project, in the Current project input field, type in string_manipulator_client and press enter.
  2. In Project Type, choose Access an existing COM component.
  3. In Component Information, click the browse button (the button with ...) and open the file $ISE_EIFFEL\examples\com\wizard\string_manipulator\string_manipulator.idl where $ISE_EIFFEL represents the path to the EiffelStudio installation directory.
  4. Click Next.
  5. In Component Type, choose In-process (*.dll).
  6. In Generation Options, click the browse button and select the directory where the project should be created (later referenced as destination folder). Choose $ISE_EIFFEL\examples\com\wizard\string_manipulator\generated\client where $ISE_EIFFEL represents the path to the EiffelStudio directory.
  7. Make sure both Compile C code and Compile Eiffel code are checked.
  8. Select Overwrite existing files.
  9. Click Generate.
  10. Wait until the wizard is done.

First look at the generated code

At the end of the processing the EiffelStudio button becomes enabled. Click on it. This will automatically start EiffelStudio with the generated project so you can more easily navigate through the created Eiffel classes.

Note:When accessing a COM component the EiffelCOM Wizard will generate a precompiled library which includes all the generated classes. This allows for easy browsing of the generated classes, however a precompilation project is read-only, so you need to start another EiffelStudio to reuse the generated classes. The interesting classes are all related to the coclass proxy STRING_MANIPULATOR_PROXY. The proxy is the Eiffel class that gives access to the component. Each feature on the proxy calls the corresponding interface function on the component. You can use the EiffelStudio opened by the wizard to browse through the generated classes and study the class hierarchy.

Implementing a client

To implement a client of the StringManipulator component open a new EiffelStudio. Create the project in $ISE_EIFFEL\examples\com\wizard\string_manipulator\client using the ecf file found in that directory. Freeze and run the project. You are now accessing the previously built component and calling functions on its interfaces! The class MY_STRING_MANIPULATOR inherits from the generated STRING_MANIPULATOR_PROXY and redefines the feature replace_substring_user_precondition. The generated interfaces include contracts for each exposed function. You can redefine the user_precondition features to implement your own preconditions.

Note: If a COM component should be added to an existing client, the generated ecf file can be added as a library.

Contracts

Contracts can be broken directly on the proxy in which case you will get a standard contract violation in the client. If contracts are broken on the server then the exception will be forwarded by the EiffelCOM runtime to the client. The feature replace_substring_user_precondition in MY_STRING_MANIPULATOR includes has some assertions.:Comment them out. Now the contract of the replace_substring feature is wrong and erroneous calls can be made. Quick melt the changes and run the client. Enter some invalid numbers in the fields used to call this feature. After you click Replace you will see an error message box warning you that a precondition was violated on the server side. This demonstrates contracts `over the wire'. The precondition was violated in the server; this exception was caught by the EiffelCOM runtime and sent back to the client.

See Also
Creating a new COM component
Creating a new component from an Eiffel Project