Accessing a COM Component

This 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. Launch the EiffelCOM Wizard. Note: if you are running Windows 7, you will need to right-click "EiffelCOM Wizard" in the start menu and select "Run as administrator".
2. In Project, in the Current project input field, type in string_manipulator_client and press Enter.
3. In Project Type, choose Access an existing COM component.
4. 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.
5. Click Next.
6. In Component Type, choose In-process (*.dll).
7. In Generation Options, click the browse button and select the directory where the project should be created (which we will later refer to as the destination folder). Choose $ISE_EIFFEL\examples\com\wizard\string_manipulator\generated\client where $ISE_EIFFEL represents the path to the EiffelStudio directory.
8. Make sure both Compile C code and Compile Eiffel code are checked.
9. Select Overwrite existing files.
10. Click Generate.
11. Wait until the wizard is done.

Temporary Work-Around

Note that because Eiffel as a language has evolved somewhat since the EiffelCOM Wizard was last released, the compile will fail on the last (Eiffel) portion of the compile. However, in this case, it is not sufficient to simply launch EiffelStudio, change the configuration, and finish the compile. The reason is that the EiffelCOM Wizard WOULD HAVE built a pre-compiled library from the C and Eiffel files just generated, and this is important because later steps in this Guided Tour depend upon that library to be there. Thus, to navigate this, you will need to execute the steps below.

1. Let the EiffelCOM Wizard compilation proceed until it fails due to a Eiffel syntax error. Leave the EiffelCOM Wizard running. We will need it below.
2. Click the EiffelStudio button to launch EiffelStudio on the project file that was generated above.
3. The first window presented is the "Choose Your Directory" dialog box. UNCHECK the "Compile project" checkbox. Then click OK.
4. Once EiffelStudio is open, click the Change Project Settings toolbar button, and navigate to Target: default in the navigation pane.
5. Set the "Void safety" setting to "No", and set the "Syntax" setting to "Transitional syntax".
6. Click OK in the Project Settings dialog box.
7. DO NOT COMPILE, but exit EiffelStudio.
8. Copy the .ECF file just modified to a safe location. In Windows Explorer, navigate to the ...\string_manipulator\generated\client\Client\ folder. Copy the .ECF file (string_manipulator_idl_client.ecf) outside the project directory temporarily (for example, to the ...\string_manipulator\generated\client\ folder. This .ECF file has the settings that will permit the EiffelCOM Wizard compilation to succeed.
9. Place this safe copy of the modified .ECF file on the clipboard, ready to copy. Navigate to the folder where you made a copy of the above .ECF file, and in Windows Explorer, while the .ECF file is selected, from the Edit menu, select Copy (or hit Ctrl-C on the keyboard to make a copy of the file on the Windows clipboard).
10. In Windows Explorer, navigate back to the ...\string_manipulator\generated\client\Client\ folder, but don't do anything yet.
11. Quickly execute the following 2 steps: A) in the EiffelCOM Wizard, click the Generate button. B) After about 2 seconds, after the files have been generated and the C/C++ compilations have started, return to the Windows Explorer window in the ...\string_manipulator\generated\client\Client\ folder, and hit Ctrl-V on the keyboard to PASTE the saved .ECF file into the folder. Confirm when it prompts you whether to replace the .ECF file that was just generated (in Windows 7, this will be a "Copy and Replace" choice).
12. Watch the EiffelCOM Wizard Output window as it completes successfully this time.
13. With Windows Explorer, navigate to the ...\string_manipulator\generated\client\Client\EIFGENs\default\W_code\msc\ folder and confirm there is a file there named precomp.lib .

Now you are ready to continue with the Guided Tour.

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